LogoLogo
What's NewDeveloper CommunitySupportStatus
  • 🚀Get Started
    • What is JourneyApps Platform?
    • Tutorial: Build your First App
      • 1. Introduction
      • 2. Create a new App
      • 3. OXIDE IDE Overview
      • 4. Hello World app
      • 5. The Data Model
      • 6. View Components
      • 7. Queries and Data Sync
      • 8. Simple Navigation
      • 9. View Stack
      • 10. Input Validation
      • 11. View Parameters
      • 12. Data Manipulation
      • 13. Responsive Apps
      • 14. Styling
      • 15. Lists
      • 16. GPS Capturing
      • 17. Relationships
      • 18. Multiple User Roles
      • 19. Deployment and Users
      • 20. Version Control
      • 21. CSV and APIs
      • 22. Conclusion
    • JourneyApps Platform Fundamentals
      • Creating a New App
        • Git-enabled Apps
      • What are Views?
      • What is the Data Model?
      • JourneyApps Syntax Basics
      • Access the Database (DB)
        • Manipulate DB Objects
        • Query DB Objects
      • View Navigation
        • Deep Linking
      • CloudCode Overview
      • OXIDE (Online IDE)
  • 💻Build your App
    • JourneyApps Syntax
      • Syntax Basics
      • Access the DB
      • View Navigation
      • Async & Await
      • TypeScript Apps (Beta)
        • runtime-build package
        • TypeScript App Troubleshooting
      • What's New in V4
        • Updating to the V4 API
    • Configure your Data Model
      • What is the data model?
      • Reference: model
        • field
        • belongs-to
        • has-many
        • index
      • Data Rules
        • Data Buckets
        • Sync Rules - Limit data synced to devices
        • Data ACLs - Limit access to data
        • Real-world example for Data Rules
        • ❔FAQs
        • Migrate to Data Rules
      • App Indexes
      • Webhooks
    • UI Components
      • All UI Components
        • actionSheet
        • Attachments
        • button
        • button-group
        • capture-coordinates
          • marker
          • marker-query
        • capture-file
        • capture-photo
        • capture-signature
        • card
          • accent
          • action
        • columns
          • column
        • component
        • context-menu
          • divider
          • item
        • CSV
        • date-input
        • datetime-input
        • dialog
          • body
        • display-3d-model
          • 📖display-3d-model Guides
            • Guide 1: Initialize and layout a 3D model in a view
            • Guide 2: Control playback position
            • Guide 3: Troubleshooting controls
        • display-coordinates
        • display-file
        • display-image
        • display-photo
        • display-signature
        • heading
        • html
          • HTML Advanced Topics
          • ❔HTML FAQs
          • 📖Guide: HTML & JourneyApps iFrame Client
        • icons
        • info
        • info-table
          • row
        • journey.photos (capture multiple photos)
        • JourneyPrinter (print PDFs)
        • grid
          • cell
          • 📖grid Examples
        • list
          • list-item
            • accent
            • asset
            • pills
              • pill
            • action
        • multiple-choice-checklist
        • navigation (Navigation drawer)
          • general-section
            • item
          • section
            • item
              • item
          • ❔navigation FAQs
        • notification
        • object-dropdown
        • object-list
          • action
        • object-repeat
        • object-table
          • action
          • column
            • action
            • edit-boolean
            • edit-date
            • edit-datetime
            • edit-integer
            • edit-number
            • edit-select
            • edit-text
            • edit-time
            • edit-typeahead
              • action
            • header-action
          • column-group
          • empty-action
          • 📖object-table Guides
            • Actions
            • Cell callouts
            • Column groups
            • Columns
            • Controlled object-table
            • Controls
            • Copy & paste data
            • Edit cells
            • Filters
            • Frozen columns
            • Fullscreen object-table
            • Mode
            • State
            • Styles
        • optionList
        • PhotonSync (transfer data offline)
        • power-bi
          • 📖Guide: PowerBI Embedding
        • scan-barcode
        • shortcut
        • sidebar
        • single-choice-dropdown
        • single-choice-radio
        • template
        • text-input
        • time-input
        • toggle
        • view
      • JS/TS Events
      • Show / Hide UI Components
      • View Templates
      • XML Fields (Attributes)
        • align-content
        • align-controls
        • align-label
        • bind
        • clear-button-visibility
        • control-order
        • disabled
        • error-message
        • icon-position
        • id
        • hide-if
        • modifier-text
        • label
        • label-case
        • label-color
        • on-change
        • on-press
        • placeholder
        • required
        • show-if
    • JS / TS APIs
      • Attachment
      • Bluetooth (Beta)
      • Broadcast
      • component
      • CSV
      • DB
      • HardwareBarcode
      • journey
        • journey.config
        • journey.container
        • journey.device
        • journey.diagnostics
        • journey.dialog
        • journey.files
        • journey.hardware
        • journey.photos
        • journey.runtime
        • journey.sensors
        • journey.viewStack
      • JourneyPrinter
      • KeyboardBarcode
      • LocalDB
      • NFC
      • OnlineDB
      • PhotonSync
      • SerialPort
      • ShortcutManager
      • TCPSocket
      • user
    • Extend your App with Custom Code
      • App packages
        • App packages overview
        • PDF report package
        • TypeScript library & unit tests
        • Manage External Dependencies
      • Custom HTML
    • Style & Customize your App
      • Style & configure UI components
        • Overview
        • Understand extendable themes
        • Use themes on a view
        • Theme specific components on a view
        • Examples
        • Debugging
        • ❔FAQs
      • Change your App Font
      • Custom Branding
        • Custom Container Features
        • Special Requirements for iOS Containers
    • Integrate your App
      • Backend integrations with CloudCode
      • Barcode Scanning
        • Barcode Scanning using Keyboard Emulation
        • Hardware Barcode Scanning
        • scan-barcode
      • Bluetooth Low Energy (BLE)
      • Broadcast API
      • HTTP requests (Fetch API)
      • JourneyApps Print (Android)
      • Maps and navigation
      • NFC
      • Opening external links/apps
      • Serial Port
      • TCP Sockets
    • Design Intuitive Apps
      • UX Guidelines
      • Write Effective Copy
  • 📱App Features
    • RealWear® Voice Control
      • Automatic Voice Commands
        • Automatic Voice Commands - Advanced
      • Manual Voice Commands
    • App, Runtime and Container Updates
    • Batch Operations (App)
    • Call JS/TS Functions from XML
    • Capture GPS Locations
    • Push Notifications
    • Translations
    • XML Format Strings
    • Webhooks (External)
  • 🌐CloudCode
    • CloudCode Overview
    • Trigger a CloudCode Task
      • Trigger CC with a Schedule
      • Trigger CC via a Webhook
      • Trigger CC from an App
      • Trigger CC from Another Task
      • Trigger CC via HTTP
    • Attachments in CloudCode
    • Timezones
    • Advanced CloudCode Topics
      • Access Multiple DBs in CloudCode Tasks
      • Batch API (CloudCode)
      • CloudCode Dependencies
      • Configure HTTPS in CloudCode
      • Deployment environment variables
      • Local CloudCode Development
      • PDF Reports using CloudCode
      • Shared CloudCode Tasks
      • Translations in CloudCode
  • 📥Backend API
    • Introduction
    • API Reference
      • Retrieve All Objects
      • Query Objects
      • Sort Results
      • Limit and Skip
      • Count Objects
      • Create a New Object
      • Retrieve a Single Object
      • Update a Single Object
      • Delete a Single Object
      • Batch Operations (v4 API)
      • Oplog API
      • Retrieve the App Data Model
      • Manage App Users and Sessions
      • Field Representation
      • Error Responses
    • API Limits
    • Update to the V4 API
  • ⚙️Technical
    • Data Synchronization Priority
    • Device Diagnostics
    • JSON1 Query Engine
    • Improve App Performance
    • Security Measures
    • Supported Platforms
      • Web Container
      • Windows Installer
    • Domain Whitelist
  • 🖥️OXIDE
    • Get started with OXIDE
      • OXIDE Overview
      • Components of OXIDE
    • Configure Testing Deployments
    • Edit and Manage Files
      • How to Navigate to a Function
      • Manage External Dependencies
    • Create and Manage App Containers
    • Debugging & Troubleshooting
      • Common Troubleshooting Pointers
      • App Diagnostics Reports
      • Build Logs
    • OXIDE Workspaces
      • OXIDE Trees
  • ❕Deprecated Features
    • Deprecated Features and Components
Powered by GitBook
On this page
  • Overview
  • Basic Example
  • Interact with the 3D model
  • Attribute and methods overview by function
  • Developer Notes
  • Standard Attributes
  • bind
  • scale
  • Advanced Attributes
  • autoplay
  • background-color
  • border-color
  • bounding-box
  • debug-normals
  • double-sided-materials
  • floor
  • fog
  • height
  • loader-color
  • loop
  • id
  • material-vertex-groups
  • offset-x
  • offset-y
  • offset-z
  • on-pick-mesh
  • placeholder
  • show-if and hide-if
  • stats
  • wireframe
  • Component Methods
  • animationStart
  • animationStop
  • computeCenterOffset
  • computeScaleFactor
  • getCamera
  • setCamera
  • getPlayhead
  • setPlayhead
  • scrollIntoView
  1. Build your App
  2. UI Components
  3. All UI Components

display-3d-model

PreviousbodyNextdisplay-3d-model Guides

Last updated 2 years ago

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 plan.

Current Limitations

  • display-3d-model currently only supports .fbx files and these files need to be zipped when 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

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

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

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 - can be a named color or #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

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

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

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.

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

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]}

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]}

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.

scrollIntoView

Programmatically scroll until the display-3d-model component is visible in the view.

Increasing or decreasing the of the model (also see the example below)

Enabling or disabling the

or animations (also see the example below)

Playing animations

Setting the of the scene

Enable or disable the ability to debug model .

on-pick-mesh is an event that calls a JS/TS or . See more details:

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

Note: Some 3D models are not centered in 3D coordinate space (0,0,0) and when coupled with the , and attributes, these can provide centering capability.

Generates a value that when used, will scale the model to an acceptable size in the current 3D viewport that will show the entire mesh.

Gets the camera position represented as a .

Sets the camera position as a . This will animate the camera to the new position.

💻
📖display-3d-model Guides
bind
normals
id
$:function
navigation
JS/TS Events
placeholder
show-if
hide-if
id
quaternion
quaternion
scale
wireframe
Starting
stopping
from a specific point
camera position
offset-x
offset-y
offset-z
scale
offset-x
offset-y
offset-z
scale
computeCenterOffset()
computeScaleFactor()
autoplay
loop
animationStart()
animationStop()
getPlayhead()
setPlayhead()
getCamera()
setCamera()
background-color
border-color
floor
fog
height
loader-color
bounding-box
debug-normals
double-sided-materials
material-vertex-groups
stats
wireframe
Enterprise
bound