# Importing Assets#

With the exception of procedural and implicit geometries that can be generated in Clarisse, static and animated geometries have to be created and brought in from other applications. Clarisse always relies on external files such as Alembics, USDs, EXRs... It can be described as an external asset assembly software.

The concept of external file is then fundamental to Clarisse. The whole workflow of the application has been designed around external assets which is why when you import assets, they are always dynamically linked to their source files as a references.

As a result, Clarisse doesn't have a native file format to store geometries or images. Its native project file is a description of items that can have links to external files. In someway, the concept is very similar to how HTML files link to external resources and like in HTML files, it is also possible to items to link to files that do not exist yet.

This aspect is very important since Clarisse has been designed to offer a non linear, non sequential referencing workflow.

Consequently, when you import a polygonal mesh in Clarisse, it is not converted and stored as a native Clarisse geometry. Instead, the geometry is described as a link to the source file along with additional attributes allowing you to manipulate it.

Each time Clarisse loads the scene back, only this simple description is loaded. It's only when the geometry is displayed in the 3D View, for example, that the source geometry file gets automatically loaded and then attributes such as a rotation or a scale, for example, are applied to the geometry.

This is always what happens each time assets defined by links to external files such as texture maps, volumes... are imported to Clarisse.

Note

Clarisse also provides a highly level node-based project assembly workflow to import assets and assemble projects. Please refer to Build Assembly Workflow for more information since there is an alternative workflow to import assets in Clarisse.

## Importing Geometries#

To import geometries, go to File > Import > Geometry... and select any supported geometry file formats or use Create > Geometry > Polymesh > Polyfile and set the Filename attribute to the geometry you want.

When you import geometries, topological data isn't saved in the project. In fact, the only thing that gets saved is the item attributes on which one of them link to the external imported file.

Note

Volumes are imported the same way. Go to File > Import > Volume or use Create > Geometry > Volume > File.

### Assigning Materials#

Materials can also directly be assigned to scene objects. To assign a material to a scene object, specify a material to the attribute Material Override. In this case materials assigned to shading groups are ignored. Only the material referenced in Material Override is evaluated.

### Updating Geometries#

If you select one polyfile and inspect its attribute in the Attribute Editor, you'll find the attribute Filename which references the filename of the geometry.

In fact, when you import items, Clarisse keeps track of the file dependency and at anytime, you're free to modify the file path to link to another geometry. When you change the filename of geometry by modifying the Filename attribute, Clarisse will automatically load the new geometry.

If materials were attached to the previous geometry shading groups, Clarisse will automatically resolve the material association for every shading groups name of the new geometry that is matching the one of the previous geometry.

## Importing Images#

There are several ways to import images (stills or image sequences). Depending on what you want to do, you can import images as a image layer or import them as texture maps. In the same way Polyfiles are referencing geometry files, images are referencing image files.

### Importing Image Files#

To import images like a image layer file, go to File > Import > Image... and browse for any supported images. This type of images are meant for layered compositing. However, it is still possible to use them as textures for materials for example. Just Create > Texture > Map and set the Image attribute to the image layer item you want to use.

### Importing Texture Maps#

To import images as texture maps, use either File > Import > Texture and browse for supported image files or Create > Texture > Map File and set its Filename attribute to the image you want to import.

## Importing Projects#

Importing projects can be really useful if you wish to work in libraries. You can, for example, save projects containing a library of materials, geometries, light sets etc... Then import them, for re-use, in an already existing project. To import a Clarisse project in the current one go to File > Import > Project... and select the project(s) you wish to import.

When you import a project, imported items are as if they were actually created in the current project. In other words, they are not brought as a reference so Clarisse doesn't keep the link to the imported project file.

If the external project that was imported was to be externally updated, the project importing the external project file wouldn't be updated. If you wish to reference a project then you need to explicitly use file referencing.

## Referencing Files#

File referencing is a way to import projects and scenes while keeping a dynamic link to sources files. That way are automatically updated in the project when source files are modified. As you can imagine there are multiple benefits to file referencing:

• Artists can freely work on their scenes while having the confidence of always being up-to-date because the referencing link ensures assets are always synchronized to the latest version.
• Artists can work and share libraries of assets that be used in many different scenes.
• File size are kept pretty small since only the path to the source asset and the attribute edits are stored when referencing a file.
• Since edits are performed as overrides, it is very easy to track what has been modified on referenced assets.

It's pretty obvious that file referencing is a super powerful feature when working in teams as multiple users can work concurrently.

Referencing assets is very easy. Use File > Reference > File... and choose the asset files to be referenced. When assets are referenced, items are created within a new context of type reference which is only defined by a Filename attribute.

The reference can be also freely changed to link another version of the asset for example. Last but not least, file referencing supports reference nesting: References can themselves reference other files.

### Reference Types#

Clarisse natively supports 3 types of references:

Format Extension
Clarisse Project project
Alembic Archive abc
Pixar's Universal Scene Description usd

Note

Using Clarisse API, it is possible to add custom types of references.

#### Alembic and USD File Layering#

Alembic and USD reference support layering so instead of working on big monolithic caches defining everything from geometry to animation, it is possible to compose a reference from multiple Alembic or USD files. Working using layers gives you access to super flexible workflow because you can use multiple cache files to define a single reference. For example, you can have a cache file that defines a static geometry used for lookdev that will be merged for lighting with a cache only defining the animation.

Note

Layering composition is directly performed by Alembic and USD libraries. Clarisse feeds the different file paths along their orders to the library and retrieve the result of the composition. Any performance loss resulting from layering is not coming from Clarisse as unfortunately, each time a layering operation is performed, these libraries reload all the different layers to perform the final composition of the asset.

#### USD Variants#

USD Variants are supported for both USD references and USD Bundles. When using USD references, you can access to variants directly using the Attribute Editor on each USD prim defining variants.

You will find them in the attribute group named USD>Variant Sets where you can choose the variant you wish to apply. If you are using a USD Bundle, variants are directly available on the geometry bundle itself through the Attribute Editor. Each prim defining variants will be listed under the Variant Sets attribute table where you can freely choose the variant you wish to apply.

#### USD Purpose#

Like USD Variants, USD purposes are supported for both USD references and USD Bundles. By default, USD files are using the purpose defined in the Edit > Preferences... under the USD section of the Project.

However, it is possible to directly override the setting on a USD reference or bundle using the Attribute Editor. Set the Purposes attribute to Custom and select the purpose(s) you wish to use.

#### USD Geometry Deduplication#

Unlike Alembic, USD does not offer any reliable way to detect all geometry duplicates of a scene. There are no built-in mechanism besides explicitly flagging prims as duplicates during export. There are a few problem inherent to USD that can rise regarding deduplication of data.

One of the issue is that information highly depend on the quality of the USD writer. If the exporter doesn't properly flag duplicates then the information is simply not there.

The other issue is that USD is not only a scene cache file. It can represent a dynamic construct that potentially references a lot of different (duplicate or not) assets making this even more complex to track duplicates.

To be efficient, Clarisse offers a way to detect geometry duplicates when loading data from a USD stage. Unfortunately, Clarisse has to do this the hard way. To detect duplicates, Clarisse has to compare each new geometry with the ones it already has in memory.

Tip

Since this process adds a potentially non negligible overhead, it is possible to disable this feature entirely in the application preferences. Go to Edit > Preferences... Under USD section, you will find the Geometry Deduplication setting which controls this feature.

Geometry Deduplication Description
Advanced Clarisse analyzes incoming geometry to automatically deduplicate data when possible to optimize memory. Depending on the scene and geometric complexity of the USD assets, this mode may be slow.
Basic Clarisse exclusively relies on USD instancing information to deduplicate data. This mode is faster but potentially uses more memory when there are duplicates in the USD assets.

This feature can also be controlled on USD References and USD Bundles. In the Attribute Editor, you will find Geometry Deduplication attribute. By default, it is set to Use Preferences so it uses the setting defined there. You can locally override this setting by changing the value to either Advanced or Basic.

Note

When kickbashing USD items outside their reference contexts, Geometry Deduplication of these items is using the setting of the preferences.

#### Pending and External Items#

Pending and external items are unresolved items that you may encounter in Clarisse. They are easily recognized since they are displayed with a red cross over their icons (when they are pending) or within a special context in the Browser or the Explorer called ext:// (in Clarisse BUiLDER exclusively).

Unlike typical items, these unresolved items are automatically generated by Clarisse. They appear when you are importing or referencing projects that are connected to items that are missing.

This typically happens when the content of a reference changes (after an external modification on the original file) or when these items haven't been loaded.

For example, let's say that in your project you are referencing a file such as an alembic or a project. In this project you are scattering a Tree geometry defined in this reference.

Now let's say, that someone deletes, moves or renames the Tree that was in the reference file. As you can imagine, Clarisse won't be able to locate the Tree item anymore when loading your project since it is missing.

What happens is that Clarisse generates a pending item in place of the missing Tree. It also updates all its connections to reflect the original scene construction as it was before the external change.

This way you know that something is now missing and potentially broken.

Another scenario that can happen is when you export contexts out of Clarisse. For example, let's imagine you have a context project://ASSETS defining a box geometry and another one, project://SCATTER defining a scatterer instancing project://ASSETS/box.

In Clarisse, nothing prevents you to export both project://ASSETS and project://SCATTER as separate projects (respectively scatter.project and assets.project).

However, since project://ASSETS/box isn't defined in the file scatter.project, Clarisse marks this link as an external dependency in scatter.project.

As a result, when you load scatter.project, Clarisse notifies you of the unresolved external dependency. If you decide instead to import or reference scatter.project, Clarisse creates, above the SCATTER context, a ASSETS/box pending item.

This way, when you reference or import assets.project, at the correct location in the context hierarchy of the project, Clarisse is automatically able to reconnect the scatterer to the box.

##### Using the node-based scene assembly#

In the context of node-based scene assembly, things are slightly different because projects are mainly brought using a ReadProject node. Unlike when running in Clarisse iFX, unresolved items are hosted in a special root context named ext://.

### Overriding items#

In Clarisse, the edit of a referenced item is called an override. Overrides are created automatically when editing the attributes of items coming from a reference. This includes the creation of custom attributes on referenced items or modifications to the filename attributes of nested references. While references are super flexible, they exhibit some limitations such as it is not possible to:

• create new items (including embedded items) in a reference.
• delete items from a reference. However it is possible to disable items.
• move items from a reference. However, they can be freely instantiated outside their reference and resulting instances continue to keep the live link to their source defined in the reference.

Tip

Identifying referenced items from others is really simple. They always display a R (for remote) on bottom left corner of their icon, as well as a lock icon. Referenced items with overrides have always their names underlined and displayed in blue in the Explorer and Browser.

It is possible to circumvent all these limitations by converting a reference to a local context. For more information please refer to Localizing References.

#### Overrides storage#

Overrides are basically a layer of modification applied on top of referenced files. Internally, they are defined by a path to the items being overridden followed by their new attribute values.

Overrides are always stored in the currently opened file referencing the asset and NOT in the referenced asset file. For example, if we referenced an Alembic asset linking to /path/to/my/asset/frog.abc and modified a couple of its attributes, the resulting project would look like:

#Isotropix_Serial_Version 1.2
Reference "frog" {
options {
filename "/path/to/my/asset/frog.abc"
}
overrides {
object "frog_eyes" {
translate -3.8 0.0 0.0
enable_subdivision_surface yes
}
}
}


In this simple case we've just referenced a single asset. What happens when we create an override in a hierarchy of references?

For example, let's say we are currently working on master.project. This project, that has been loaded in Clarisse, references refA and refB that are themselves referencing refC, refD, refE.

graph TB
A(master)-->B(refA)
A-->C(refB)
B-->D(refC)
B-->E(refD)
C-->E
C-->F(refE)

In this case all overrides will be stored in master.project. Moreover, if master.project was to be referenced in another Clarisse project, all overrides created in master.project will be still applied. This ensures that the content of master.project is always consistent whereas it is loaded or referenced in Clarisse.

For more information on how overrides are physically stored in Clarisse files please refer to Referencing and Overrides.

#### Removing Overrides#

Overrides can be removed by selecting the reference and clicking on the Clear action in the Attribute Editor. When removing overrides, attribute values are then restored to their original values as they are defined in the referenced file. Overrides can also be cleared:

• by using the Attribute Editor and on the overridden attribute and selecting Revert Value.
• by on a referenced item in the Browser or Explorer and choosing Revert Overrides in the pop up menu.
• by using the Explorer to select an override defined on an item and pressing the Del key.
• by on the referenced context in the Browser or Explorer and choosing Revert Overrides in the pop up menu.

#### Cleaning up Overrides#

The overriding system always keeps overrides even if they are not applied. This typically can happen when reloading a reference on which items have been renamed or deleted externally. To prevent an undesired accumulation of dangling overrides, users can choose to cleanup references by selecting clicking on the Cleanup action on the reference using the Attribute Editor. This will only deleted dangling overrides. It will not affect any overrides that are currently applied to the reference.