Please enable JavaScript to view this site.

Clarisse 5.0 Reference Guide

This section covers the technical aspects related to configuration files and environment variables allowing you to customize the application so that it is extended to meet your specific needs.

Customizing Units

It is possible to customize units in the application using a custom unit configuration file. To specify a custom unit configuration file, go to Edit > Preferences... > Units and set Units File accordingly. Please refer to units.cfg file found in the application binary folder for more information.

Customizing Startup

Clarisse startup can be customized so that it executes a specified script or creates a custom default scene.

Startup Script

It is possible to automatically execute startup scripts in Clarisse that is always launched when Clarisse is executed. This can be very useful to edit default value of classes etc... To specify a custom startup script, go to Edit > Preferences... > General and set Startup Script accordingly. Please note that it is possible to specify multiple scripts using the ; or : separator (Windows platform only supports ; separator). Alternatively, it is possible to override the value of the built-in environment variables: CLARISSE_DEFAULT_STARTUP_SCRIPT and CLARISSE_STARTUP_SCRIPT

Startup Scene

It is possible to specify the default Clarisse startup project when Clarisse is first launched or when the user go to File > New > Scene. To specify a custom startup Clarisse project, go to Edit > Preferences... > General and set Startup Scene accordingly.

Customizing Widget Association

It is possible to customize default widget associations by modifying the default widget association configuration file. For more information please refer to Widget Association Configuration.

Customizing File Format Color Space Mapping

It is possible to customize the file format/color space mapping by specifying a custom configuration file defined by Color Space Mapping Config File found in Edit > Preferences... > Color Management. Here's an example of the resolution preset configuration file:

#Isotropix_Serial_Version 1.1

Open_EXR {

   extensions "exr, sxr, tx"

   color_space "Clarisse|Cineon"

}

Basic {

   extensions "jpg, jpeg, png"

   color_space "Clarisse|sRGB"

}

 

 

For more information on file format and color space association please refer to Color Management.

Customizing Resolution Presets

It is possible to customize image resolution presets used by various items in Clarisse by specifying a custom configuration file defined by Resolution Preset Config File found in Edit > Preferences... > Rendering. Make sure to enable Use Resolution Preset Config File and restart the application to take the settings into account. Here's an example of the resolution preset configuration file:

#Isotropix_Serial_Version 1.1

// This is an example of a custom resolution configuration file.

TV_Resolutions {

 FHD_1080p {

   display_name "1080p (1,920x1,080)"

   width 1920

   height 1080

   aspect_ratio 1.0

 }

 UHD_2160p {

   display_name "2160p (3,840x2,160)"

   width 3840

   height 2160

   aspect_ratio 1.0

 }

}

Computer_resolutions {

 VGA {

   width 640

   height 480

   aspect_ratio 1.0

 }

 SVGA {

   width 800

   height 600

   aspect_ratio 1.0

 }

}

 

As you can see the syntax is pretty straight forward the first block defines the category and each embedded blocks defines the resolution such as:

#Isotropix_Serial_Version 1.1

Category {

 ResolutionName1 {

   display_name "My First Resolution"

   width 256

   height 256

   aspect_ratio 1.0

 }

 ResolutionName2 {

   display_name "My Second Resolution"

   width 256

   height 256

   aspect_ratio 1.0

 }

}

 

Where:

  • display_name is used to specify the name of the preset in the user interface. If you omit the display_name tag, Clarisse will automatically fallback to the name of the resolution block.
  • width defines the width of the resolution preset.
  • height defines the height of the resolution preset.
  • aspect_ratio defines the display pixel aspect ratio of the resolution preset.

Customizing Image Buffers/AOVs

It is possible to customize image buffers/AOVs so that they are automatically declared to the application. To specify a custom Image Buffer/AOVs configuration file, go to Edit > Preferences... > Rendering and set Aov Config File to the configuration file you wish to use. Make sure to enable Use Aov Config File and restart the application to take the settings into account. Custom AOVs defined in the configuration file are considered as built-in and are not editable using the Image Buffer Editor. Here's an example of a configuration file:

#Isotropix_Serial_Version 1.1

variance {

 blend_mode 0

 visual_hint_mode 0

 bit_depth 2

 bit_type 2

 description "defines the variance of the image"

 channels "s2"

}

world_coordinate {

 blend_mode 0

 visual_hint_mode 1

 bit_depth 2

 bit_type 2

 description "define a world coordinate"

 separator "_"

 channels "x" "y" "z"

}

Blend Mode

The blend_mode tag defines how subpixels should be blended by the renderer when outputting the AOVs. For more information please refer to Opacity Blending Modes.

Value

Mode

0

Use Opacity

1

Use First value

2

Use Last Value

3

Use Min Value

4

Use Max Value

Description

The description tag is an optional string description of the image buffer to describe its purpose for example.

Visual Hint Mode

The visual_hint_mode tag defines how the image buffer should be interpreted by the Image View. For more information please refer to Visual Hint Mode.

Value

Visual Hint

0

Color

1

Raw

2

Black And White

3

Black And White (Normalized)

4

Heat Map

5

Heat Map (Normalized)

6

Normal

Image Buffer Depth

Image buffer depth is encoded using the 2 following tags bit_depth and bit_type where:

Bit Depth Value

Description

1

8-bit

2

16-bit

4

32-bit

Bit Type

Description

1

integer

2

floating point

So to specify an image buffer that is output as 16-bit float you'll have to write:

bit_depth 2

bit_type 2

Channels

The channels tag defines the number and the names of the channels of the image buffer. Please note that Clarisse supports a maximum of 4 channels per image buffer.

Separator

The separator tag defines the separator character to use to split the name so that it can be displayed hiearchically in the AOV Editor. For example, if we declare 2 image buffers my_custom_aov1 and my_custom_aov2 with the separator _ they will be displayed such as:

 

Clarisse Environment Variables

Clarisse can be customized using a set of dedicated environment variables. These variables support multiple file paths using the : or ; separator while Windows platform only supports ;

Variable

Description

IX_PYTHON2HOME

Define in which folder Python 2.7x is installed.

IX_PYTHON2PATH

Define the path of Python 2.7x runtime libraries.

IX_PYTHON3HOME

Define in which folder Python 3.7x is installed.

IX_PYTHON3PATH

Define the path of Python 3.7x runtime libraries.

IX_PYTHON_API_PATH

Define the location of Python version files such as python bindings, python Clarisse engine location, shelves scripts... This variable is automatically set by Clarisse and read-only. It is used for internal purposes.

IX_SHELF_CONFIG_FILE

Define which folders Clarisse should look for shelf configuration files. In the event multiple folders have been specified, Clarisse appends the content of each configuration file that are found in each folder.

IX_SHELF_SCRIPT_PATH

Define which paths Clarisse uses when resolving scripts defined by  a filename with no folder specified. The variable supports multiple paths. In that case the path resolution is ordered and stops at the first resolution.

IX_SHELF_ICON_PATH

Define which paths Clarisse uses when resolving icons defined by  a filename with no folder specified. The variable supports multiple paths. In that case the path resolution is ordered and stops at the first resolution.

IX_MENU_CONFIG_FILE

Define which folders Clarisse should look for script configuration files. In the event multiple files have been specified, Clarisse appends the content of each scripts. By default, Clarisse looks for a file named init_menus.py

IX_MENU_SCRIPT_PATH

Define which paths Clarisse uses when resolving scripts defined by  a filename with no folder specified. The variable supports multiple paths. In that case the path resolution is ordered and stops at the first resolution.

IX_MENU_ICON_PATH

Define which paths Clarisse uses when resolving icons defined by  a filename with no folder specified. The variable supports multiple paths. In that case the path resolution is ordered and stops at the first resolution.

CLARISSE_DEFAULT_STARTUP_SCRIPT

Define the location of the default startup script executed by Clarisse each time the application is launched.

CLARISSE_STARTUP_SCRIPT

Define the location of a custom startup script executed by Clarisse each time the application is launched. This variable is not defined by default.

Customizing the Shelf

It is possible to customize the shelf by using a specific configuration file. Here is an example of the shelf configuration syntax:

shelf {

 slot 0 {

   category "new_category" {

     shelf_item {

       title "Execute my item"

       description "my item"

       script_filename "./items/my_item.py"

       icon_filename "./icons/icon.png"

     }

   }

 }

}

 

In the previous example, a new shelf item named Execute my item is be defined to the slot 0 of the shelf using the icon defined by the file located in ./icons/icon.png. When executed, Clarisse calls the file ./items/my_item.py. Note the category block which corresponds to the name of the tab on which the script will be included in. Here, the script Execute my item is included in new_category.

 

When the script_filename doesn't specify any folder, Clarisse uses the content of the variable IX_SHELF_SCRIPT_PATH to locate the file. When the filename is relative such as "./path/to/my/file.py" then Clarisse resolves the path using the folder where it found the configuration file and which used eventually the IX_SHELF_CONFIG_FILE variable.

 

For example, if Clarisse finds the shelf configuration file shelf.cfg in /clarisse/shelf1 the relative path of filenames defined in shelf.cfg is naturally resolved to /clarisse/shelves. As Clarisse supports and appends multiple shelf.cfg file, each relative path defined in each shelf.cfg is resolved accordingly to the corresponding shelf.cfg path.

clarisse

+- shelf1

 +--- shelf.cfg

   +--- general

      +--- unparent.py

      +--- unparent.png

+- shelf2

 +--- shelf.cfg

   +--- general

      +--- parent.py

      +--- parent.png

 

This path resolution works exactly the same way for icons.

Customizing the application menu bar

It is possible to entirely customize the application menu bar using Python scripts. Here are a few examples showing how to create custom menus. In the following example we will create a new menu with an action bound to a shortcut and an icon.

ix.application.get_main_menu().add_command("File>")

 

item = ix.application.get_main_menu().add_command("File>Open...", "./open.py", "ctrl+o")

item.set_icon(ix.api.GuiResource.open())

 

ix.application.get_main_menu().add_command("File>")

Here, we're adding a File menu entry to the application menu bar.

 

item = ix.application.get_main_menu().add_command("File>Open...", "./open.py", "ctrl+o")

Then we add an Open menu item bound to the shortcut Ctrl+O which will execute the script open.py

 

item.set_icon(ix.api.GuiResource.open())

Finally we attach an icon to the menu item.

 

Here, we will add a script that will be called each time the File menu will be displayed. This is very useful for creating menus dynamically or to enable/disable menu items according to the current selection

ix.application.get_main_menu().add_show_callback("File>", "./_show.py")

 

Here, we remove all commands in Open Recent Menu

ix.application.get_main_menu().remove_all_commands("File>Open Recent>")

 

Enabling or disabling menu or a menu item.

ix.application.get_main_menu().enable_command("File>Revert", ix.application.get_current_project_filename() != "")

ix.application.get_main_menu().enable_command("File>Open Recent>", ix.application.get_recent_files().get_count() > 0)

 

Getting a specific menu item

open_item = ix.application.get_main_menu().get_item("File>Open...")

 

Display a custom message in the status bar when hovering on a menu item

open_item.set_description("Open a project")

 

Execute a command attached to a menu or a menu item

ix.application.get_main_menu().exec_command("File>Open...")

 

Move specified menu item position after specified one.

menu.move_command("File>New>", "File>Quit")

 

Move menu position

# move menu position

menu.move_command("Tools>", "Edit>")

# Result : Edit | Tools

 

menu.move_command("Tools>", "Edit>", False)

#Result : Tools | Edit

Passing arguments to scripts

Populate dynamically Open Recent menu and associate corresponding filename to each menu item.

open_recent_show.py:

from os.path import basename

 

menu = ix.application.get_main_menu()

menu.remove_all_commands("File>Open Recent>")

 

item = menu.get_item("File>Open Recent>")

if item != None:

   working_directory = item.get_working_directory()

 

recent_location = ix.application.get_recent_files()

for i in range(recent_location.get_count()):

   filename = basename(recent_location[i])

   file_path = working_directory + '/open_recent_action.py'

 

   command = "variables = {'project_path': '" + recent_location[i] + "'}\n"

   command += "execfile('" + file_path + "', variables)"

 

   item_path = "File>Open Recent>" + str(i+1) + "    " + filename

   menu.add_command_as_script("ScriptingPython", item_path, command, "", recent_location[i])

 

 

open_recent_action.py:

import ix

 

# Request the user if Clarisse should save the project if it's modified

request, filename = ix.check_need_save()

if request.is_yes():

   ix.application.save_project(filename)

 

if not request.is_cancelled():

   if project_path != "":

       clarisse_window = ix.application.get_event_window()

       old_cursor = clarisse_window.get_mouse_cursor()

       clarisse_window.set_mouse_cursor(ix.api.Gui.MOUSE_CURSOR_WAIT)

       ix.application.disable()

       ix.application.load_project(project_path)

       ix.application.enable()

       clarisse_window.set_mouse_cursor(old_cursor)

Customizing the Material Editor

It is possible to define which nodes can be created/instantiated or imported as guest nodes in the Material Editor using a configuration file. The location of the configuration file can be changed in Edit > Preferences... > Nodal View and set Config File located in the Material Editor section in the panel. Using the configuration file, you can add your custom modules so that they become loadable and even instantiable even when they don't inherit Material or Texture classes.

Creatable classes

A creatable class is a class of items that can be created in the Material Editor. Textures and Materials are mandatorily creatable/instantiable, but the Material Editor is customizable since you may for example want to:

  • make Displacements non instantiable
  • make Image instantiable
  • add custom classes or simply reorder the left tree sub-widget

All instantiable classes are obviously marked as importable (see below) in the Material Editor.

Syntax

instantiable {

 class_name "MyInstantiableClass" ["ItsUiName"]

}

 

The optional "ui name" parameter is exclusively used to specify the name of the category the class appears in the left tree widget. By default, the OfClass name is used.

Importable classes

An importable class is a class of items that can be imported (displayed) in the Material Editor as guest nodes. By default, all non-instantiable classes with a texturable attribute or a reference attribute accepting Texture/Material/AovStore/Image can be imported as guest nodes. For user convenience, Camera and Image are also flagged as importable since they can be referenced in TextureSpatial and TextureMap.

 

Importable classes can be extended to let the Material Editor import custom classes as guest nodes. This is typically very handy when you need to import specific classes to display a consistent texture network that is made of custom classes. For example custom FooTexture class that would allow connections to BarItem classes. BarItem class could then be added to the importable list so that connected BarItem to FooTexture items are properly imported as guest nodes in the Material Editor.

Syntax

importable "MyClass1" "MyClass2"...

Filterable classes

A filterable class is a type of class for which the Material Editor displays a class filter button in its toolbar. Typically filterable classes should be root nodes of texture networks like Materials and Lights for example. Filterable classes are automatically imported along with their upstream texture graph in the Material Editor when selected in the application. Note that this behavior can be deactivated when unchecking its filter class button.

 

You can extend the Material Editor to support more filterable classes by using the syntax below.

Syntax

filterable "MyClass1" "MyClass2"...

 

Isotropix

Copyright (C) 2009-2022 Isotropix. All rights reserved.