Customizing Clarisse#

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.

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.

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.

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.

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.

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.

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 raytracer when outputting the AOVs. For more information please refer to Opacity Blending Modes.

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.

Image Buffer Depth#

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

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 ;

Application 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.

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.

flowchart TB
A(clarisse)-->B(shelf1)
B-->C[shelf.cfg]
B-->D(general)
D-->E[unparent.py]
D-->F[unparent.png]
A-->G(shelf2)
G-->H[shelf.cfg]
G-->I(general)
I-->J[parent.py]
I-->K[parent.png]

This path resolution works exactly the same way for icons.

Application Main 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.

Adding a new menu#

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("Asset>")

item = ix.application.get_main_menu().add_command("Asset>Add...", "./add_asset.py", "shift+ctrl+o")
item.set_icon(ix.api.GuiResource.open())

Code breakdown#

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

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

item = ix.application.get_main_menu().add_command("Asset>Add...", "./add_asset.py", "shift+ctrl+o")

Then we add a Add menu item bound to the shortcut Ctrl+Shift+O which will execute the script add_asset.py

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

Finally we attach an icon to the menu item.

Calling a script when displaying a menu#

Here, we will add a script that will be called each time the Asset menu is hovered/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("Asset>", "./_show.py")

Cleanup Menu Entry#

Here, we remove all commands in a submenu. In this example we will cleanup the content of the Open Recent submenu located in File menu

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

Enabling/disabling a menu item#

Here is how to enable or disable a 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...")

Displaying custom messages in the status bar when hovering on a menu item#

open_item.set_description("Open a project")

Executing a command attached to a menu or a menu item#

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

Moving specified menu item position after a specified one#

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

Moving 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.

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])

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)

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 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"...