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
3D models with textures are not currently supported.
It is not possible to toggle hidden layers, groups, or elements.
Basic Example
For more examples, see our guides:
📖pagedisplay-3d-model GuidesInteract 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:
Increasing or decreasing the
scale
of the model (also see the example below)Enabling or disabling the
wireframe
Playing animations from a specific point
Setting the camera position of the scene
Example: Programmatic controls
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 |
Developer Notes
Performance consideration: In general, the larger the file the worse the performance will be, especially on a mobile device (such as a RealWear HMT). File size will be directly proportional to the number of polygons and the number and characteristics of the materials included in the model (even if those materials are not actually used)
As a rule of thumb, aim for a file size of under 5 MB. Practically this may mean unnecessary high fidelity elements should be removed from their original models to reduce the polygon count, and by extension the file size.
Unused (and non visible) materials should be removed from models before they are exported to FBX to limit the file size.
Materials: The use of materials is generally supported however, trial and error in terms of which materials work well is recommended.
Standard Attributes
bind
pagebindbind
scale
scale
Optional
Type: Number
Default: 1.0
Specify the scale of the model.
Advanced Attributes
autoplay
autoplay
Optional
Type: boolean
Default: true
Specify whether the model animation should automatically start playing when the model is loaded.
background-color
background-color
Optional
Type: string
(#hex value)
Default: #a0a0a0
Specify the background color of the component.
border-color
border-color
Optional
Type: string
- can be a named color or #HEX value
Default: #546e7a
(Light theme); #90a4ae
(Dark theme)
Specify the border color of the component.
bounding-box
bounding-box
Optional
Type: boolean
Default: false
Enable or disable the bounding box of the model.
debug-normals
debug-normals
Optional
Type: boolean
Default: false
Enable or disable the ability to debug model normals.
double-sided-materials
double-sided-materials
Optional
Type: boolean
Default: true
Enable or disable double-sided materials.
floor
floor
Optional
Type: boolean
Default: true
Enable or disable the floor of the model.
fog
fog
Optional
Type: boolean
Default: true
Enable or disable a background fog effect.
height
height
Optional
Type: Number
Default: 700 px
Specify the height of the component in pixel.
loader-color
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
loop
Optional
Type: boolean
Default: true
Specify whether the model animation should play in a loop.
id
pageidid
material-vertex-groups
material-vertex-groups
Optional
Type: boolean
Default: true
Enable or disable the material vertex groups.
offset-x
offset-x
Optional
Type: Number
Default: 0
Specify the offset of the x-axis.
offset-y
offset-y
Optional
Type: Number
Default: 0
Specify the offset of the y-axis.
offset-z
offset-z
Optional
Type: Number
Default: 0
Specify the offset of the z-axis.
on-pick-mesh
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:
placeholder
pageplaceholderplaceholder
show-if
and hide-if
pageshow-ifpagehide-ifshow-if
and hide-if
stats
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
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'})
is called from JS/TS:
animationStart
animationStart
This method starts the animation of a model.
animationStop
animationStop
This method stops the animation of a model.
computeCenterOffset
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.
Example:
computeScaleFactor
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:
getCamera
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
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
getPlayhead
Returns: The playback position in milliseconds.
Gets the playback position.
setPlayhead
setPlayhead
Parameter: The playback position in milliseconds.
Sets the playback position.
scrollIntoView
scrollIntoView
Programmatically scroll until the display-3d-model
component is visible in the view.
Last updated