Template Assets

This guide will walk you through the setup of template model and material assets, which enables you to automate configuration setups that require hundreds or thousands of assets.

Introduction

Some projects may require working with hundreds or even thousands of assets. Setting up configuration manually on each of these assets would be very time consuming, and prone to user error. The use of a template asset would enable us to concentrate the logic setup in one single asset, and apply it automatically to all of the uploaded assets.

This means that we would get the following benefits:

1. No need to add any logic inside uploaded 3D models to assign materials or swap components

2. No need to add node-tags to specific nodes on uploaded model assets - could use Node-queries with a given naming convention instead

3. No need to create unique materials for every material option

4. Changing the properties of a family of materials (Cotton, Leather, etc.) is easier with a single template asset

5. No need to add tiling information to every uploaded texture - the tiling could exist on the template material in a Tiling Override Operator

Basic Setup without Templates

Scalable Setup With Templates

Template Setups are highly dependent on a strong and consistent naming convention for filenames and node names. Names that separate elements with underscores will make it easier to automaticaly parse and identify the assets and nodes.

Template Materials

A Template material is a configurable material that can change some of its properties based on the catalog item that references it. These template materials are very useful for describing either entire material families, or every single material choice.

For example, you could have a template cotton material that has unique properties for roughness, specularity, and bump map, while the base map is swapped for every color or pattern choice within that family. Another material family, like Leather, would have its own separate material template.

Material Family Template

In the case of a general material template, you would be swapping all the customizable properties with textures. This is the more typical scenario for scanned materials, which result in unique textures for all the major properties of the material. If tweaks are necessary, the adjustments are baked into the textures directly with a tool like Photoshop.

General Material Template

Basic Setup

With the basic setup we are able to make use of template materials without the need for asset queries using metadata. This setup is suitable for small sets of material choices, as there is some manual work involved. It is also the most performant setup, as asset queries incur a small delay while the search is being processed.

In this setup we work with an intermediary proxy material that helps store the unique properties for each material choice:

Basic Material Template Setup with Proxy Materials

In this example, we have a configurable template material where only the Base Color and Base Map properties change based on material choice. The BaseColor attribute is of type color, and the DiffuseMap attribute is of type asset-texture.

We make use of the Proxy Material asset in order to store the unique values for the BaseColor and DiffuseMap attributes specifically for the Cotton Red material. This is essentially the equivalent of a Material Instance inside Unreal Engine.

Catalog Item

Material Proxy With Unique Attribute Values

Proxy Material Referencing the Cotton Template

Cotton Template Logic

The Proxy Material can then be duplicated for additional Cotton options, and the only thing that needs to be adjusted are the default values for the configurable attributes BaseColor and DiffuseMap. Unfortunately, this makes the process partially manual, but it still allows us to keep the material properties all located on a single material asset - Cotton_Template_MAT. Automation with a custom web application can eliminate the manual aspect almost entirely.

Advanced Setup

For a more scalable approach, we need to automate the loading of textures in the material without the need for the intermediary Proxy Material asset. This will require us to rely on metadata field matching between the textures and the corresponding catalog items:

Advanced Material Template Setup

This setup will require that we have metadata fields on both the catalog items and on the texture assets, to identify the two and match them together, and the use of metadata and asset queries inside the logic.

In the example above we are working with two metadata fields Name and Family, while the textures may have an additional field called Type which would help us differentiate between different types of textures required by that material (diffuse, roughness, bump, etc.).

We would also need to rely on some local attributes inside the Cotton Template material to hold the results of the queries before we can use them.

This is what the logic setup would look like:

Catalog Item

Texture Asset

Material Template Logic

Please note that in the rule titled "Find and Assign the Texture Maps" we are performing the query for the texture and assigning it to the Base Map property of the material with a single Set Property Action.

Color Property Automation

In some scenarios it may be needed to include color attributes as well to these template materials, in addition to the asset-texture attributes. This could be for a color tint that gets multiplied with a texture asset inside the template material. If you would like to add automation for these color attribute as well, then you have two basic options available:

Attribute Propagation

You could create a color attribute on both the Template Material as well as on every catalog item representing the material choices - let's call it BaseTint. The value of it could be set individually on every catalog item, and it would propagate that value to the template material.

The downside of this approach is that practically speaking you would want to avoid doing this manually. The attributes on the catalog items with their values would typically need to be generated automatically from spreadsheet data.

Data Table Entries

This alternative might be the more practical one, as you can store the hex codes for these color entries inside a spreadsheet, and upload that spreadsheet to ThreeKit as a Data Table. You can then make use of datatable queries to read the hex code into a string attribute inside the material template, and convert it to a color attribute using a custom code snippet. See this example recipe.

Template Models

The goal of a 3D model setup is to allow us to upload 3D models for either products or components, and have them automatically pulled in by the configurator without the need for manual setup in terms of material assignments or component switching.

For this setup we will take the Advanced Material Template setup listed above, and enhance it with some additional logic to automate material or component assignments.

Template Model Workflow Example

STEP 1

We start by following the procedure described in the Advanced Material Templates example listed above, by querying the metadata field itemCode on the parent Item. This will enable us to find the appropriate model to load in Step 2.

STEP 2

The Product_Template asset in this example contains a Model Reference node. This node is meant to receive the model queried by the Asset Query logic. This can be done in a single step using the Set Model action.

STEP 3

Using Node Queries we can find the nodes that start with Fabric_ in their name from the asset loaded in the Model node. We can then assign the material stored by the Fabric attribute to the result of this query.

Item Setup

STEP 1 - Query Metadata

STEP 2 - Query and Assign Model

STEP 3 - Query Nodes and Assign Materials

Metadata Management

As seen above, both the material and model templates can leverage metadata to automatically load assets into the template. Metadata management would thus be necessary at scale on assets without the need to generate it manually, which is both time-consuming and error prone.

The metadata on Catalog Items would ideally be generated during the data import process, when using spreadsheets to generate the catalog items. Currently this can only be achieved through a custom web application that uses the ThreeKIt Rest APIs to manipulate the catalog.

For 3D assets, the metadata can be automatically generated based on the asset file names. This requires that file names follow a strict naming convention, as shown in the examples above, where fields are typically separated by underscores.

Once the assets are imported into the project's org on ThreeKit, you can make use of a custom web app to assign the metadata automatically based on the asset names.

The Apply Metadata Pattern custom app can be added to your projects for this purpose.