Custom Configurators

VNTANA’s robust API makes it easy to build custom configurators. Use our API to create custom 3D configurators. You can add multiple choice options and build out your front-end UX to provide your customers with infinite possibilities. This requires front-end developer resources which we can recommend or your team can use our documentation to build themselves.

Woman's • Flat

THE VNTANA SHOE CLASSIC

$140

Select a Width & Size

The very definition of classic sneaker. This is our iconic VNTANA first debuted in 1416, the first rubber-soled canvas shoe of its kind.

Extended widths available
Classic canvas upper
4 eyelet lace up sneaker

ADD TO BAG

The VNTANA Configurator allows users to interact with and modify a 3D model. Instead of creating a 3D model for every possible combination of features for a single product, you can create a single file containing all the necessary geometry and simply provide the additional maps to the configurator. Whether for Quality Assurance purposes or to create the perfect purchase, this will allow your team or customers to easily view and customize the product without the need to re-load the model into the viewer.

The configurator provides two basic types of modifications: modifying the appearance of the model by changing material properties like base color or roughness textures, and modifying the model’s geometry by toggling the visibility of particular meshes. Since we may want to apply these changes to multiple models at once, the configurator groups meshes into “mesh groups” which are identified by mesh names. Mesh groups and operations, as well as additional viewer settings, are specified in a simple JSON file from which the configurator is generated.

In order to build the configurator you will need to utilize the JS Component of the VNTANA Viewer. See this guide for more information.

Designing the Asset

In order for a 3D model to work with a custom Configurator, it must be designed with configuration in mind. Ultimately, the components of your 3D model which are interchangeable are up to you, however that which will be changed must be accessible from the Viewer. Additionally, each type of change that can be made will require different information to ensure they can be swapped.

Changing Colors

The simplest configuration that can be implemented is a solid color swap for a given mesh. Using a mesh “group”, the configurator would simply apply a new color to all applicable meshes. Bear in mind that this is not the same as changing textures.

In our example, we will simply apply it to all meshes that are contained in the “group” Laces here. We will demonstrate later how to indicate the mesh “group” using the meta.json file. Color changes can be applied to all meshes as well.

Changing Textures

Unlike simply changing a solid color of a mesh, in order to swap textures on a mesh within the Configurator, the relevant maps must be available. When designing your 3D asset with meshes that can have textures swapped, generate all sets of maps required for each texture configuration, and save them externally to the GLB in their own folder, i.e. insoleMaps/map.png. The meta.json file will need to indicate the URL (file path) of each necessary map that can be applied.

An example folder structure is shown below, with the image on the right showing the location of the 3D Model to load in the folder model and the image on the left showing the contents of the textures folder. In the demo, there are only two options for a texture “material” change and the default textures need to be contained in the GLB itself, so there is only one set of textures in this folder.

It is not necessary that the 3D Model data be stored in the same location as the configurator. If you choose to access these from another location you simply need to exactly reference their location in the meta.json file. The meta.json file is expected to be found in the relative location ‘./meta.json’.

Changing Geometry

Finally, some 3D models may have geometry that can vary. In order for the Configurator to be able to swap certain geometries, each desired mesh option must be superimposed within the same GLB and the names of the meshes that’ll change must be specified in the meta.json file. The Configurator will then toggle the visibility of these meshes as needed.

Using the Configurator - meta.json

The VNTANA Custom Configurator modifies a model by two basic operations on meshes: changing the appearance of meshes by modifying their material properties, and hiding/showing the meshes to change a model’s geometry. These operations and the meshes they target are specified by a JSON file called meta.json from which the configurator is automatically generated.

Mesh Groups

Before specifying the operations of our configurator, we need to define the targets on which they will be performed — mesh groups. Each mesh group is defined by its unique name and an array of strings. A mesh will be a member of a group if and only if its name starts with some string in the array, or prefix. It is the responsibility of the model designer to provide easily discernible mesh names. Mesh groups are specified under the “groups” property of the JSON file.

If an operation should be performed on only one mesh, its name should start with a unique prefix.

For example, we can define mesh groups as follows:

“`
“groups”: {
“laces”: [“Lace”],
“tongue”: [“Tongue”],
“sock-liner”: [“Sock”],
“sole-flat”: [“Sole001”],
“sole-engraved”: [“Sole002”]
}
“`

Mesh group “laces” will contain all meshes whose name start with “Lace”, while “sole-flat” will contain all meshes with “Sole001” at the start of their name. Each group can have more than one prefix included, for example you could have the group “soles” containing mesh prefixes ["Sole001", "Sole002"]. This would mean that meshes with either of these prefixes would have the same operation applied to them, so for mesh changes these meshes would either both be hidden or both be shown.

Prefix strings are case-sensitive.

Operations

Operations are specified under the “operations” property of the JSON file. For each of the properties of this model an HTML select element is created with a property key as its label. The values of these properties are operation definitions. These definitions specify the type of the operation (material change or visibility toggling), groups of meshes on which it acts, default value and alternative options, each of which introduces changes to the meshes of the mesh group(s).

A higher-level example of the “mesh” type “operations”:

“operations”: {
operation-label: {
“type”: “material” or “mesh”,
“groups”: array of group names,
“default”: default option-label,
“options”: {
“option-label” : “mesh-prefix”
}
}
}

where “option-label” refers to an HTML option element which is created under the corresponding select element, and “mesh-prefix” is the prefix added to the “groups” above.

Changing Material Properties

Material changing operations have their “type” set to “material”, and can act on multiple mesh groups at once specified under the “groups” property. The changes that should be made to material properties are determined by the option objects provided in the “options” property. These changes will be applied to every mesh inside any of the mesh groups listed in the “groups” array.

Changes introduced by “default” option are assumed to be already present in the model.

For example, suppose we want to add color selection to the configurator. A selected option should change the base color of each material present in the model. Since color is a material property, we set the “type” to “material” and we will use the “laces” group to alter the color of each of the lace meshes. Under the “options” property we specify each of the possible color values that we provide by first stating the option-label (“White”, “Red”, “Light Blue”, …), and then an object with desired changes. The only change here is the base color, so it is the only property in the option definition. Since JSON files don’t support hex notation for numbers, hex values are provided as strings. (the “0x” prefix is optional).

“operations” : {
“Lace Color”: {
“type”: “material”,
“groups”: [“laces”],
“default”: “White”,
“options”: {
“Pink”: {
“color”: “0x6c2c47”
},
“White”: {
“color”: null
}
}
}
}

The “White” option is set to default and is assumed to already be present in the model, that is, all lace materials should have the color set to “White”. We can specify it directly in the JSON as with other colors, or can just specify “null” which tells the configurator to read this value directly from the model.

As another example we may want to change material textures. A common decision is to change metalness, roughness and normal textures in tandem. We again assume that textures needed for the “White” option are already provided in the model, so we can read them directly from some mesh of a mesh group specified under “groups”.

On the other hand, textures needed for the “Aquamarine” option aren’t present in the model, so they need to be loaded. Each texture is specified by an object containing the “url” property with the URL to the texture image (value can be set to null instead of a string if the property shouldn’t be used) , and an optional “config” property in whose value we can store additional texture settings. These settings are the same as that of THREE.js textures. Since texture images used in this example were already flipped, we set the “flipY” property to false.

“Sock Liner”: {
“type”: “material”,
“groups”: [“sock-liner”],
“default”: “White”,
“options”: {
“Aquamarine”: {
“map”: {
“url”: “./model/insoleMaps/map.png”,
“config”: {
“flipY”: false
}
},
“metalnessMap”: {
“url”: “./model/insoleMaps/roughnessMap.png”,
“config”: {
“flipY”: false
}
},
“roughnessMap”: {
“url”: “./model/insoleMaps/roughnessMap.png”,
“config”: {
“flipY”: false
}
},
“normalMap”: {
“url”: “./model/insoleMaps/normalMap.png”,
“config”: {
“flipY”: false
}
}
},
“White”: {
“map”: null,
“metalnessMap”: null,
“roughnessMap”: null,
“normalMap”: null
}
}
}

List of Modifiable Material Properties

Name	Description	Type	Example
color	Base Color	Color	"color: 0xAFAFAF"
map	Base Color Texture	Texture	"map" : { "url" : "path/to/texture" }
metalnessMap	Metalness Texture	Texture	"metalnessMap" : { "url" : "path/to/texture" }
roughnessMap	Roughness Texture	Texture	"roughnessMap" : { "url" : "path/to/texture" }
metalness	Metalness Factor	Number	"metalness" : 0.2
Roughness	Roughness Factor	Number	"roughness" : 0.5
emissiveIntensity	Emissive Intensity Factor	Number	"emissiveIntensity" : 0.8
emissive	Emissive Color	Color	"color" : "0xBABABA"
emissiveMap	Emissive Texture	Texture	"emissiveMap" : { "url" : "path/to/texture" }
normalMap	Normal Texture	Texture	"normalMap" : { "url" : "path/to/texture" }
aoMap	Occlusion Texture	Texture	"aoMap" : { "url" : "path/to/texture" }
aoMapIntensity	Occlusion Strength	Number	"aoMapIntensity" : 0.1
clearcoat	Clearcoat Factor	Number	"clearcoat" : 0.5
clearcoatRoughness	Clearcoat Roughness Factor	Number	"clearcoatRoughness" : 0.2
clearcoatMap	Clearcoat Texture	Texture	"clearcoatMap" : { "url" : "path/to/texture" }
clearcoatRoughnessMap	Clearcoat Roughness Texture	Texture	"clearcoatRoughnessMap" : { "url" : "path/to/texture" }
clearcoatNormalMap	Clearcoat Normal Texture	Texture	"clearcoatNormalMap" : { "url" : "path/to/texture" }

Toggling Mesh Visibility

Operations of this type have their “target” set to “visibility”, and their “groups” property is again an array of mesh group names. Each of the options specified under the “options” property is of the form “label: mesh-group”. Once an option is selected, all meshes within its corresponding group are made visible, while all other meshes in all remaining mesh groups specified under the “groups” property are hidden. It is mandatory that a mesh occurs in at most one mesh group across all “visibility” operation groups.

For example, suppose that we want to change the sole in the model. The “sole-flat” mesh group comprises the mesh “Sole001”, while the group “sole-engraved” comprises the mesh “Sole002”. The default mesh is thus “Sole001”, and it will be made visible on configurator initialization.

“Sole”: {
“type”: “visibility”,
“groups”: [“sole-flat”, “sole-engraved”],
“default”: “Flat”,
“options”: {
“Flat”: “sole-flat”,
“Engraved”: “sole-engraved”
}
}

As with the other operations, the option-labels will be used to identify the meshes in the HTML select element, in this case “Flat” and “Engraved”.

Resources