Variation Json and Variation Manager

The Variation Manager

The variation manager is the tool for managing your variations.
Environment variables in your file paths are allowed. 

From the "File" menu, you can save/load your variations to/from a file. You can also reload the content of the table from the scene (Reload from Atoms) or save your changes to the scene (Register to Atoms).

Once you "Register to Atoms" all the data will be stored as a json string in the tcAtomsNode of your scene.

As first thing a user should add a new agent type and give it a name. This should be exactly as your agent type name. You can do this by pressing the "Add agent type" button.

If you right-click on the list a menu with the following options will appear:

• Add Agent Type

• Remove Agent Type

• Duplicate Agent Type

Geometry Tab

In the Geometry tab, you can create and manage new geometries using any geometry supported file (i.e. geos, fbx, usd, etc).
To add new entries just right click on the list and press on "Add Entry".
You should give unique names for each entry. Environment variables in your file paths are allowed. 

Since multiple geos can be contained in a single geometry file you can use the filter entry to select some geos. Use the * character as a wildcard and ! character as exclusion symbol. Use the comma to separate multiple entries. (i.e. _head,robot1_legs,!robot2_*)

Material Tab

In the Material tab, you can create and manage materials for your variations.

Right click on the viewport and click on "Add Entry" to create a new material.

Rendering

Each material can be rendered in the following two modes:

• A material file, depending on which renderer you will be using: .ass (Arnold), .rib (Renderman), .vrscene (vray), .rs (Redshift).

• Parameter settings in the Preview/Render section. 
  In this section, users can provide a diffuse weight and one or more diffuse slots, each slot contains a color and an optional map.
  To add new diffuse slots, right click on the "Diffuse" item and select "Add Diffuse" from the popup menu.
  In case no diffuse file is specified for a slot, the diffuse color will be used. 
  The diffuse slot can be driven by a metadata (IntMetadata) which name must be specified in the "Diffuse Slot Metadata Name" section. 
  Users can also change the Hue of the diffuse with another metadata which name must be specified in the "Diffuse Hue Metadata Name". Please find below the valid ranges for the hue as well as the metadata type for each render engine.
  Additionally users can also assign specular and normal settings to the material.

Preview

The Preview/Render section is also useful for setting up the preview data which will be used later by Atoms to display variations in the viewport.

The main difference between the rendering side is that the diffuse slot can only be selected with the "colorVariation" intMetadata. In case no diffuse file is specified, the diffuse color will be used.

The same thing happens for specular path and color, although there is only one slot for these.

There are also several other properties:

• diffuse and specular weights

• specular roll off and eccentricity

• normal map path

The preview support also UDIM textures. Put <udim> inside the texture path.

For example: C:/MyProject/textures/body_diffuse.<udim>.png

Variations Tab

The "Variations" tab contains the list where the agent type variations are defined. 

Each entry will contain geo-material combinations and an optional LOD list.

If you right-click on the list a menu with the following options will appear:

• Add group

• Remove group

• Copy To Lod: this action will copy all the geo-materials combinations from the combinations list to a new lod.

You can right click on the "Combinations" or "LOD" lists and press "Add Entry" to create new entries.
From the dropdown lists you will be able to select the geos and materials available from the Geometry and Material tabs.

Overrides Tab

The "Overrides" tab contains the list of the available overrides.
Overrides define ways to add or filter geometries from your variations; an override can add and filter geometry at the same time.

The "Combinations" tab contains the list of geometries (and their associated material) to add.
The "Filters" tab contains the list of the geometries to be filter.

If you right-click on the list a menu with the following options will appear:

• Add override

• Remove override

Tree Tab

The "Tree" tab contains the definition of a Variation Tree, which is a system for building variations at runtime as opposed to a predefined list of combinations.
You are able to drag and drop materials and geos from the lists accessible on the right tabs onto the items described below.

With a variation tree, users can define variation types which then gets instanced at runtime. A variation tree can contains the following items:

• Variation Types: typically contains a list of geometries and optionally any other available item except material overrides.
  
  
  

• Geometries:  Geos also can belong to a variation type and to an extra geo group. Geos can also be nested (multiple level). To nest a geo select a geo from the tree and press the "add geo" button.
  Each “weightable” geo has a lock button next to the geo name. The user can lock a geo by pressing that button.

  If your locked mesh is:

  • not a child of another “weightable/lockable” geo, then it is going to be added to each variation of that VariationType.

  • a child of another “weightable/lockable” geo, then it is going to be added to each variation of that that VariationType only if the parent geo is added to the Variation.

  Please note, if you have any other unlocked geo/geos at the same level of a locked geo, the standard workflow will be applied: one of those geos will be picked according to their weights.
  
  
  

• Extra Geo Groups: Extra geo groups can be nested under a variation type or at the global level. They are used for adding extra geometry to a variation. Only one geo per extra geo group will be picked for each variation.
  
  There is also a None element under each extra geo group. If you wish to not have extra geo in all variations of the same type, you should set the weight of the "None" to a value higher than 0.
  
  
  

• Material Overrides: Material overrides can only be applied to geometries and are used for assigning specific materials to such geometry when building a variation.
  
  
  

• Exclude Geo: Exclude geos ensure a certain piece of geometry is not added to a variation when another geometry is already included in such variation.
  
  
  

• Material Constraints: Material constraints ensure a specific material is assigned to a geo whenever another material has been already picked for another geo.
  
  For instance, you might want to have the jackets and trousers of your characters to have the same color, or have a specific hair material when a skin material is selected.
  When the source material and the destination material contain both a "*", then the string matched in the source material name will be applied to the destination material. Alternatively, you can provide the "*" wildcard only for the destination material.
  
  If no material is found for the provided constraints, then the material search will fall back to the standard search (see below).

Atoms will build variations at runtime following the rules you have setup in the variation tree. An important aspect of this building process consists in the material selection as Atoms cannot render or preview geometry without a material. As it would very tedious to assign a material with material overrides for every geometry in the tree, you can use the option tab to specify rules for searching for a material starting from the geometry name (this is only possible if the materials have been built following a predefined naming convention).
You can build such rules in the Options tab:

• Material Prefix: a material prefix used for the material search.

• Geo-Mat Suffix replacement: when searching for materials, this replaces the first value with the second value in the current geometry name. Users can use "*" inside the second value to make the search of the material more flexible (i.e. "_*_MAT" for materials ending with "_black_MAT", "_brown_MAT", etc.)

• Geo-Mat Alias: a list of replacements performed on the mesh name. For instance, if you have two meshes named "suitClosed_GEO" and "suitOpen_GEO" and they both work with materials named like "suit_black_MAT", "suit_brown_MAT", etc. you should specify in this list two aliases: "suitOpen" - "suit", "suitClosed" - "suit".

The Geometries and Materials tabs contain all the available geometries and materials. The items of those lists cab be dragged on the tree items.

The Preview tab shows the preview for the selected variation type. No preview will be shown if a variation type or one of its children is not selected.
At the bottom, the following options can be found:

• Seed: the random seed for the variation tree. Different values will produce different results.

• Random: if this option is on a different variation is going to be generated every time the tree selection changes or the Generate button is pressed. If it is off, you can still generate different variations by changing the seed and pressing the Generate button.

• Verbose: when this option is on, log messages will be printed out in your host application. These messages are helpful to understand the logic and steps of the variation tree.