3d and material assets

Basic workflow

1. Upload 3d file

You can upload .glb and .babylon files to create a 3d asset.

GLB is a default format for 3d models and widely known across the web.
Most 3d tools support exporting in GLB format, and 3d model exchange platforms typically offer models in GLB format as well.

Babylon files are representing Babylon.js scenes in JSON format.
These kind of files are more powerful than GLB files, as additional Babylon.js specific features and technologies can be provided within the files.
Babylon files are typically created by exporting manipulated scenes from Babylon.js tools like the sandbox or the playground.

Material extraction

The system automatically extracts material definitions from the uploaded 3d file and creates new material assets inside a folder called Materials3d.

If a material asset with the same name already exists in the Materials3d folder, the existing material will not be overwritten. Instead, the existing asset will be linked to the uploaded 3d asset.

2. View and adjust data of 3d asset

The 3d asset UI displays specific data about the model, helping the user get an impression of the 3d file's content.

• Nodes: the structure of meshes and transform nodes

• Materials: list of material assets that are assigned to nodes within the 3d asset

• Tags: list of tags that are assigned to nodes within the 3d asset

• Animations: animation groups that are defined in the 3d asset, see Babylon.js docs for detailed information about animations

When selecting a certain node, you will see specific data of this node.

• Material: link to material asset

• Tags: list of assigned tags

• Transformation: position, rotation and scaling information of the node

• Morph targets: technology for interpolating mesh geometry, see Babylon.js docs for detailed information about morph targets

Material assignment

The material-to-node assignment is established during the initial upload when creating a new 3d asset. The user can then manually change this material assignment by selecting a different material asset.

Each subsequent file upload will not overwrite the existing material assignment to preserve the user's changes. However, if new nodes are present in the upload, material assignments will still be created for these new nodes.

Tag assignment

"Tags" are a concept of Babylon.js for grouping objects like nodes or materials, see Babylon.js docs for detailed information about tags.
These tags can then be used as parameter subject of the viewer controls “set parameter values” slot or in the viewers “parameter manager” API.

Similar to materials, tags are extracted from the 3d file only during the initial upload to preserve any changes made by the user. Users can modify tags within the node editor by adding, removing, and creating new tags.

3. Adjusting material assets

As mentioned previsouly, material assets are automatically extracted and created when uploading a 3d model.
Material assets can also be created manually by clicking the “+ New” button, however this feature only supports PBR materials.

There are 2 editors, “Basic” and “Expert”.

The “Basic” editor offers a UI for the most common material properties, available exclusively for PBR materials. This is because material properties vary significantly across different types of materials, and PBR materials are by far the most common ones in use.

The “Expert“ editor represents the “raw” JSON description of the material.
The user has full power to add, remove or modify certain properties to tweak the material.
Some properties like id, name or customType are ignored though, as they will be overwritten by the system in a later step.

Since the user modifies the JSON string directly, it's possible that the string could become invalid, such as by removing commas or colons. In such cases, the material becomes invalid and cannot be saved. However, the editor helps identify where JSON errors occur, and you can still click “Discard changes” anytime if you encounter issues.

Upload texture images & use them in materials

If your uploaded 3d model contains materials with textures, you will most likely receive some warnings in extracted material assets after the model upload.
These warnings indicate that the images, which represent the dedicated textures, are not uploaded yet.
You can easily do this by clicking the “Upload image” button in the corresponding texture channel.

This action will automatically create an image asset in the Textures3d folder and links this image asset to the material texture channel.
You can also upload your images manually into the Textures3d folder and select them in the material texture channel dropdown menu.

4. Assign bundle to configurator

See How to assign bundles to configurators for detailed description.

5. Use 3d & material assets in configurator

After assigning the asset bundles to the configurators, 3D and material assets can be utilized within the configurator. You'll need to create a viewer control to visualize these assets.

If no further action is taken, you may encounter two outcomes:

• If there is exactly one 3d asset among all assigned asset bundles, that model will be visible immediately.

• If there are multiple 3d assets, all models will be hidden by default, requiring manual handling of model visibility.

Handling model visibility and applying parameter can be done in 2 ways.

Hive

Use viewer controls “set parameter values” slot.
This is the go-to solution for simple projects, as it eliminates the need to set up a custom code environment.

Custom Code

For more advanced requirements you can establish a custom code setup where you have the full power of the combeenation viewer API, Babylon.js and Typescript in general.
Tey components for interacting with 3D and material assets include the ModelManager and ParameterManager though.

6. Upload & use viewer environment file

In terms of 3d scene customization the user has the possibility to define an “environment”, which is responsible for image based lighting (IBL).
See Babylon.js docs for further info about environments and IBL in general.

The environment file (.env) is represented by a file asset.
You can then create a component which provides the URL of the uploaded environment file e.g. using the following Hive rule:

// "Cups3d" = Name (or alias) of bundle assigned to configurator
// "env" = Folder name in which "studio" is located
// "studio" = Asset name
Cups3d.env.studio.url

This component can be added to the environment parameter or slot in the viewer control.