3d viewer control

The 3d viewer control gives you the power to showcase your 3d models in the configurator. It allows you to dynamically compose the shown scene & change it at runtime so that the user always sees what he's about to buy.

Amongst other things, the 3d viewer gives you the following options to dynamically adjust the scene:

• Show & hide complete models
• Show & hide specific nodes of a model
• Changing certain aspects of specific nodes of a model:
  • Reposition, rotate & scale nodes
  • Change shown materials & adjust material details like color, roughness, metallness etc.
• Draw dynamically generated content like text or images onto nodes paintables

Once the user is happy with what he sees, he can use the control's built in AR mode to experience the customized model in an very engaging manner.

How to show models

After creation, the 3d viewer control shows all babylon assets from all asset bundles which are assigned to your configurator.

You can use the set parameter values slot to overwrite this behavior and actively define which models it should show or not.

How to alter 3d models

You can use the set parameter values slot to control most dynamic aspects of the scene like which models & nodes are shown, which materials & colors are used etc.

Properties

Besides the general control properties like width, height, background etc., the 3d viewer control comes with some special properties:

Viewer version

The 3d viewer control is powered by our own 3d viewer and we give you the freedom to chose the exact version which should be used by the 3d viewer control.

When first creating the control, we automatically set this to use the latest available version so you don't have to touch this at all.

Please consult the 3d viewer release notes when changing the viewer version to get an idea of what might change with the new version.

The option Injected is used when extending the viewer control's capabilities by custom JS. See 3d viewer control with custom JS for more details on how to use this.

Load in editor

When set to false, no 3d content will be loaded when inside the design editor. This can be helpful in situations where you're working on things which are not related to the shown 3d content like overall configurator layout or logic.

This setting only affects the design editor & does not change the 3d viewer control's behavior in preview or published configurators.

Environment URL

The environment is responsible for reflections and indirect lighting of the 3d scene. Without this and without any other lights, all materials in the 3d scene are rendered completely black.

It is recommended to use *.env files with this property.

Use the set environment URL slot, if you like to use a file from the asset editor or if you like to dynamically change the environment at runtime.

See 3d viewer docs for more details on 3d viewer environments in general.

Slots

You can use the following slots of the 3d viewer control to interactively change the 3d scene and its shown 3d content at runtime:

Set parameter values

The set parameter values slot is the central piece of the 3d viewer control which lets you adjust the scene to your likings & change it based on the users input in the configurator.

This slot lets you:

• Define which 3d models are visible or not
• Use the viewers tag parameter system to show or hide nodes & set other parameters like used materials, color, position etc.

Basic usage

The set parameter values slot needs to be connected to a value component which creates a list of records from the Viewer3d type parameter functions modelParameter, tagParameter, nodeParameter or materialParameter.

E.g.:

[
  // Set visibility of 3d models
  //
  //                      Babylon asset path,       parameter name, value
  Viewer3d.modelParameter(Models3d.CoffeeCup,     "visible",      true),
  Viewer3d.modelParameter(Models3d.CoffeeCoaster, "visible",      false),
  
  // Set parameter values using the tagging system
  // Here: Show all nodes which contain the tag "Handle" and hide all nodes 
  // which contain the tag "Cap"
  // Also set "metallic" value to 1 for all materials which contain the tag "Metal"
  //
  //                    Tag name, parameter name,   value
  Viewer3d.tagParameter("Handle", "visible",        true),
  Viewer3d.tagParameter("Cap",    "visible",        false),
  Viewer3d.tagParameter("Metal"   "metallic",       1)
  
  // Set parameter values using the node system
  // Here: Hide the node with the name "Spoon" & set a material for it which
  // will be applied once the value of the "visible" parameter is changed to
  // `true` at a later point
  //
  //                     Node name, parameter name, value
  Viewer3d.nodeParameter("Spoon",   "visible",      false),
  Viewer3d.nodeParameter("Spoon",   "material",     "SilverMat"),
  
  // Set parameter values using the material system
  // Here: Set color red and roughness 0.1 to material "matHandle" 
  //
  //                         Material name, parameter name, value
  Viewer3d.materialParameter("matHandle",   "color",        "(255, 0, 0)")
  Viewer3d.materialParameter("matHandle",   "roughness",    0.1)
]

In real live, you'll usually get the parameter values from other components whose result changes based on some user input or product logic:

[
  // "CupIsVisible" & "HandleColor" are components
  Viewer3d.modelParameter(Models3d.CoffeeCup, "visible", CupIsVisible),
  Viewer3d.tagParameter("Handle", "material.color", HandleColor),
]

Available 3d models

With Viewer3d.modelParameter you can show or hide all babylon assets from all asset bundles which are assigned to your configurator.

If you're not sure about the names, open the dev tools whilst in the design editor in which the 3d viewer control is loaded and search for the latest console log starting with "The following variant instances". When bootstrapping, the viewer prints the names of all available models with this log.

Available tag, node and material parameters

With the tag, node and material parameter functions you can either use the viewers built in parameters or you can use custom parameters which are defined & handled by custom JS.

The available built in parameters for nodes are the following:

• visible
• scaling
• position
• rotation
• material

The available built in parameters for materials are the following:

• color
• roughness
• metallic
• paintable

Tags can be used for nodes and materials alike, therefore viewer3d.tagParameter supports all built in parameters in general.

Custom parameters

When using custom parameters, you pass the name defined by setParameterObserver to Viewer3d.tagParameter, Viewer3d.nodeParameter or Viewer3d.materialParameter.

See 3d viewer control with custom JS to get more information about how to define them in custom JS.

Set environment URL

Allows you to use an environment from the asset editor and/or change the environment dynamically at runtime.

Usually you use an environment from the asset editor by creating a value component which provides the URL of the environment file 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

You can then connect this component to the Set environment URL slot.

See environment URL property & 3d viewer docs for more details about environment files in general.

Auto focus camera

This slot can be used to move the camera to a position where all active nodes in the scene are visible.

Calling this slot with default parameter values also adjusts the cameras panning sensibility as well as its pinch & wheel precision to provide a good usability regardless of the size of the shown models.

The slot accepts the following optional parameters to adjust this default behavior to your likings:

• Alpha, Beta & Radius factor to adjust the final camera position.
• Adjust panning sensibility, Adjust pinch precision & Adjust wheel precision to define whether those camera settings should be auto adjusted or not.
• Exclude tags & Exclude nodes to exclude the given nodes from the calculation.
  Both those parameters expect a coma separated list of node or tag names like tagName1, tagName2, tagName3.

See the viewers autofocusActiveCamera for more details about the parameters.

Start AR

The AR mode can be activated with the Start AR slot.

The viewer automatically detects if the device is capable of showing the model in an augmented reality environment. The minimum requirement for an AR capable device is that it comes with a camera (mobile phones, tablets), but also some browser and operating system limitations are considered.

Have a look at Googles AR core documentation for more details about AR capabilities.

AR capable devices

If the device is AR capable, the augmented reality scene will be entered automatically.
The user will be redirected to the corresponding app, which is responsible for showing the configured 3d model in the AR environment.

Non AR capable devices

If the configurator is started from a PC or if the used mobile device doesn't match the AR requirements, the viewer will show a QR code instead, which can then be scanned by an AR capable mobile device.

The QR code will lead to the exact same AR endpoint that would be reached when starting the AR journey from an AR capable device directly.

Slot parameter

• QR subtitle, QR description: Customizable text for QR code layer ("See the product at home" & the text below in the screenshot above).
• Preparation text: Customizable text for the load mask which is shown whilst the 3d model is being prepared for the AR scene
• Exclude tags, Exclude nodes: Filter for hiding certain nodes in the AR scene
• Environment: HDR environment for the AR viewer on the mobile device
• Loading screen logo: Image URL for logo on the AR loading screen

How to draw dynamic content on the 3d model (paintables)

The material parameter paintable can be used to draw images on certain meshes, as detailly described in the viewer docs.

Here are some tips and tricks for practical usage of this parameter.

1. Use GraphicView.Value.ToText() to use the content of a Graphic component as paintable

   // uses the SVG content of "PaintableGraphic" as paintable texture for the
   // material "mat_paintable_front"
   Viewer3d.materialParameter(
     "mat_paintable",
     "paintable",
     PaintableGraphic.Value.ToText()
   )
   

2. Use Hives built in flat JSON type to add properties to the paintable, followed by .ToText()

   // negative UV scaling for inverting the image
   Viewer3d.materialParameter(
     "mat_paintable",
     "paintable",
     { src: PaintableGraphic.Value.ToText(), uScale: -1, vScale: -1 }.ToText()
     // Instead of the following which yields the same result but is harder to write:
     // """{ src: {=PaintableGraphic.Value.ToText()}, uScale: -1, vScale: -1 }"""
   ),
   

3. Create individual components for paintable parameters with large string values (eg: SVGs)

   The whole component value will be updated by the server, whenever a change within the component has been detected.
   This can lead to larger network load if large string values are involved, which can be the case when using SVGs or data strings in the paintable parameter.

   It can be avoided, if the parameters are split across multiple components.
   Each of these parameter components has to be linked as an individual "set parameter values" slot though.

   // ❌ Don't: Single component "ParameterValues"
   [
     Viewer3d.tagParameter("Handle", "visible", HandleVisible),
     Viewer3d.tagParameter("HandleMat", "color", HandleColor),
     Viewer3d.materialParameter(
       "mat_paintable",
       "paintable",
       PaintableGraphic.Value.ToText()
     )
   ]
   // If component "HandleVisible" changes, the whole content of the component 
   // "ParameterValues" will be updated, even if the graphic component 
   // "PaintableGraphic" didn't even change
   // => 🔥 Lots of unnecessary network load
   

   // ✅ Do instead: Split into 2 components with 2 SigSlos:
   // Component "StandardParameterValues"
   [
     Viewer3d.tagParameter("Handle", "visible", HandleVisible),
     Viewer3d.tagParameter("HandleMat", "color", HandleColor),
   ]
   
   // Component "PaintableGraphicParameterValue"
   [
     Viewer3d.materialParameter(
       "mat_paintable",
       "paintable",
       PaintableGraphic.Value.ToText()
     )
   ]
   // If component "HandleVisible" changes, only the component 
   // "StandardParameterValues" will be updated
   // Component "PaintableGraphicParameterValue" stays untouched
   // => 👍 Less network load
   

4. Be cautios when interacting with other properties of the paintable material

In fact only the materials albedoTexture is changed when applying the paintable value. Therefore all other material properties, like roughness or metallic can be added on top.
However some of these properties may have an undesired interaction with the paintable texture.

4.1 Albedo Color

The materials albedoColor, which is set by the color parameter, will be layered with the "albedoTexture" from the paintable.
The resulting texture will be a mixture of "albedoTexture" and "albedoColor" .
If this is not desired, make sure to set the "albedoColor" to white, in this case the paintables original color will be preserved.

Texture with turquoise color, albedo color is set to white.
Original turquoise color is preserved.

Turquoise texture overlapped with red albedo color.
Original turquoise color is altered.

This also works the other way around. If you want to control the paintables color via the "albedoColor" property you have to make sure, that the original paintable image is completely white as well.

4.2 Transparency Mode

You may face the issue that transparent areas of paintable images appear black.

This can be fixed by setting the transparencyMode of the desired material to 3, which is "alpha test and blend".

Extension with custom JS

If you need more functionality than the 3d viewer control provides out of the box, you can use custom JS to extend it by adding custom parameter observers, adjusting the auto generated spec and much more.

See 3d viewer control with custom JS for more details on how to do this.