Links

display-3d-model

Overview

The display-3d-model UI component embeds and displays 3D models (in .fbx format) for a user to interact with.
Version compatibility
display-3d-model was introduced in version 4.84.0 of the JourneyApps Runtime.
display-3d-model is currently only available for customers on the Enterprise plan.
Current limitations
  • display-3d-model currently only supports .fbx files and these files need to be zipped when bound to the component. E.g. my-animation.fbx.zip

Basic Example

main.view.xml
<!-- The attachment needs to be a zipped FBX file, e.g. my-animation.fbx.zip -->
<var name="scene" type="attachment" media="any" />
<display-3d-model bind="scene" scale="0.1" />
main.js
function init() {
var animation = DB.animation.first();
view.scene = animation.scene;
}
For more examples, see our guides:

Interact with the 3D model

Once a model is loaded in display-3d-model, a user can interact with it by using their mouse or by using controls that programmatically manipulate the 3D model.

Interact with the mouse

  • Rotate the scene: Users can drag their mouse around in the 3D model. The scene will rotate around the current center of the viewer.
  • Pan / translate the scene: While holding the shift key, users can drag their mouse around. Dragging left and right will pan the scene horizontally, while dragging up and down will pan the scene vertically.

Interact programmatically

Developers can set up controls (e.g. a button-group containing multiple buttons linked to JS/TS functions) that allow users to manipulate various attributes of the 3D model. Configurable attributes and component methods are described further below in this document.
Examples of controls that a user might need include:
Example: Programmatic controls
main.view.xml
<var name="scene" type="attachment" media="any" />
<var name="scale" type="number" />
<display-3d-model id="example" bind="scene" scale="scale" />
<button-group mode="row">
<!-- Controls to allow users to increase or decrease the scale -->
<button label="-" on-press="$:scaleDown()"/>
<button label="+" on-press="$:scaleUp()"/>
<!-- Controls to allow users to start/stop animation -->
<button label="Start Animation" on-press="$:startAnimation()"/>
<button label="Stop Animation" on-press="$:stopAnimation()"/>
</button-group>
function init() {
var animation = DB.animation.first();
view.scene = animation.scene;
view.scale = 0.1; // Set the default scale
}
function scaleUp(){
view.scale *= 10; // Increase scale by 10
}
function scaleDown(){
view.scale /= 10; // Decrease scale by 10
}
function startAnimation(){
component.display3dModel({id: "example"}).animationStart();
}
function stopAnimation(){
component.display3dModel({id: "example"}).animationStop();
}

Attribute and methods overview by function

The table below summarizes the available attributes and component methods for display-3D-model grouped according to their primary or most common function. Each of the listed attributes is described later in this document.
Function
Attributes
Geometry
Animation
Camera
Styling & Display
Troubleshooting

Standard Attributes

bind

scale

Optional
Type: Number
Default: 1.0
Specify the scale of the model.

Advanced Attributes

autoplay

Optional
Type: boolean
Default: true
Specify whether the model animation should automatically start playing when the model is loaded.

background-color

Optional
Type: string (#hex value)
Default: #a0a0a0
Specify the background color of the component.

border-color

Optional
Type: string (#hex value)
Default: #546e7a (Light theme); #90a4ae (Dark theme)
Specify the border color of the component.

bounding-box

Optional
Type: boolean
Default: false
Enable or disable the bounding box of the model.

debug-normals

Optional
Type: boolean
Default: false
Enable or disable the ability to debug model normals.

double-sided-materials

Optional
Type: boolean
Default: true
Enable or disable double-sided materials.

floor

Optional
Type: boolean
Default: true
Enable or disable the floor of the model.

fog

Optional
Type: boolean
Default: true
Enable or disable a background fog effect.

height

Optional
Type: Number
Default: 700 px
Specify the height of the component in pixel.

loader-color

Optional
Type: string (#hex value)
Default: #546e7a (Light theme); #90a4ae (Dark theme)
Specify the color of the loader animation that displays when the component loads a model.

loop

Optional
Type: boolean
Default: true
Specify whether the model animation should play in a loop.

id

material-vertex-groups

Optional
Type: boolean
Default: true
Enable or disable the material vertex groups.

offset-x

Optional
Type: Number
Default: 0
Specify the offset of the x-axis.

offset-y

Optional
Type: Number
Default: 0
Specify the offset of the y-axis.

offset-z

Optional
Type: Number
Default: 0
Specify the offset of the z-axis.

on-pick-mesh

Optional
Default: unset
Triggered when: A user clicks on the model
Event parameter: $meshes
Return value: An array of objects
on-pick-mesh is an event that calls a JS/TS $:function or navigation. See more details:
main.view.xml
<var name="scene" type="attachment" media="any" />
<display-3d-model bind="scene" scale="0.1" on-pick-mesh="$:onPick($meshes)" />
main.js
function onPick(meshArray) {
for (var i = 0; i < meshArray.length; i++){
console.log(meshArray[i]);
// Example:
// Object{name: "Plane"}
}
}

placeholder

show-if and hide-if

stats

Optional
Type: boolean
Default: false
Enable or disable debug info about the model such as the frames rendered per second. These are displayed in the top-left corner of the component if available.

wireframe

Optional
Type: boolean
Default: false
Enable or disable the wireframe of the model.

Component Methods

The following component methods are available when an id is assigned to the component and component.display3dModel({id:'my-id'}).xxx is called:

animationStart

This method starts the animation of a model.

animationStop

This method stops the animation of a model.

computeCenterOffset

Returns: Array, e.g. [0,408.6,0]
Generates an array with offsets for each axis (x,y,z) that centers the model on-screen.
Note: Some 3D models are not centered in 3D coordinate space (0,0,0) and when coupled with the offset-x, offset-y and offset-z attributes, these can provide centering capability.
Example:
main.view.xml
<var name="scene" type="attachment" media="any" />
<var name="offsetx" type="number" />
<var name="offsety" type="number" />
<var name="offsetz" type="number" />
<display-3d-model id="example" bind="scene" offset-x="offsetx" offset-y="offsety" offset-z="offsetz" />
<button label="Center" on-press="$:computeOffsets()" />
main.js
function computeOffsets() {
var offsets = component.display3dModel({id: "example"}).computeCenterOffset();
view.offsetx = offsets[0];
view.offsety = offsets[1];
view.offsetz = offsets[2];
}

computeScaleFactor

Parameter: Number that represents the scale
Generates a scale value that when used, will scale the model to an acceptable size in the current 3D viewport that will show the entire mesh.
Note: This is useful because not all 3D models use the same scale factor.
Example:
main.view.xml
<var name="scene" type="attachment" media="any" />
<display-3d-model id="example" bind="scene" scale="scale" />
<button label="Fit" on-press="$:computeScale()" />
main.js
function computeScale() {
var scaleFactor = 550;
view.scale = component.display3dModel({id: "example"}).computeScaleFactor(scaleFactor);
}

getCamera

Returns: The current camera position as an Object, e.g. {position: [100.00000000000001, 200, 299.99999999999994], rotation: [-0.1505711418828577, 0.1583076573177903, 0.024434332593631213, 0.9755357401230101]}
Gets the camera position represented as a quaternion.

setCamera

Parameter: The specified camera position as an Object, e.g. {position: [100.00000000000001, 200, 299.99999999999994], rotation: [-0.1505711418828577, 0.1583076573177903, 0.024434332593631213, 0.9755357401230101]}
Sets the camera position as a quaternion. This will animate the camera to the new position.
Tip: This method is also useful when creating 3D step-based workflows (because the camera animates to a specified position).

getPlayhead

Returns: The playback position in milliseconds.
Gets the playback position.

setPlayhead

Parameter: The playback position in milliseconds.
Sets the playback position.