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.
Last updated
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.
Last updated
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:
No need to add any logic inside uploaded 3D models to assign materials or swap components
No need to add node-tags to specific nodes on uploaded model assets - could use Node-queries with a given naming convention instead
No need to create unique materials for every material option
Changing the properties of a family of materials (Cotton, Leather, etc.) is easier with a single template asset
No need to add tiling information to every uploaded texture - the tiling could exist on the template material in a Tiling Override Operator
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.
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.
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.
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 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.
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.
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:
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:
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.
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:
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.
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.
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.
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.
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.
In this setup we work with an intermediary that helps store the unique properties for each material choice:
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 inside the logic.
The Product_Template asset in this example contains a . 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.
Using 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.
