Skip to main content

View3D

class View3D extends Component implements OptionGetters<Omit<View3DOptions, "on">>

See:

constructor

new View3D(root, options)

Creates new View3D instance.

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
rootstring | HTMLElementA root element or selector of it to initialize View3D
optionsView3DOptions✔️{}An options object for View3D

Throws: View3DError

Properties

VERSION

staticreadonly

Current version of the View3D

Type: string

renderer

readonly

Renderer instance of the View3D

Type: Renderer

scene

readonly

Scene instance of the View3D

Type: Scene

camera

readonly

Camera instance of the View3D

Type: Camera

control

readonly

OrbitControl instance of the View3D

Type: OrbitControl

autoPlayer

readonly

AutoPlayer instance of the View3D

Type: AutoPlayer

model

readonly

Current Model displaying. null if nothing is displayed on the canvas.

Type: Model | null

animator

readonly

ModelAnimator instance of the View3D

Type: ModelAnimator

ar

readonly

ARManager instance of the View3D

Type: ARManager

annotation

AnnotationManager instance of the View3D

Type: AnnotationManager

rootEl

readonly

Root(Wrapper) element of View3D that given in the constructor

Type: HTMLElement

initialized

readonly

Whether the View3D is initialized. This is set to true just before triggering "ready" event.

Type: boolean

loadingContext

readonly

An array of loading status of assets.

Type: Array<LoadingItem>

plugins

readonly

Active plugins of view3D

Type: Array<View3DPlugin>

src

Source URL to fetch 3D model. glb / glTF models are supported.

Type: string | null

Default: null

iosSrc

Source URL to fetch 3D model in iOS AR Quick Look. usdz models are supported.

Type: string | null

Default: null

dracoPath

URL to Draco decoder location.

Type: string

Default: https://www.gstatic.com/draco/versioned/decoders/1.4.1/

ktxPath

URL to KTX2 texture transcoder location.

Type: string

Default: https://unpkg.com/three@0.134.0/examples/js/libs/basis/

meshoptPath

URL to Meshoptimizer decoder js path.

Type: string | null

Default: null

fixSkinnedBbox

Sometimes, some rigged model has the wrong bounding box that when displaying on three.js (usually converted glTF model from Sketchfab)
Enabling this option can resolve that issue by recalculating bounding box size with the influence of the skeleton weight.

Type: boolean

Default: false

fov

A vertical FOV(Field of View) value of the camera frustum, in degrees.
If "auto" is used, View3D will try to find the appropriate FOV value that model is not clipped at any angle.

Type: "auto" | number

Default: "auto"

center

Center of the camera rotation.
If "auto" is given, it will use the center of the model's bounding box as the pivot.
Else, you can use any world position as the pivot.

Type: "auto" | Array<number>

Default: "auto"

yaw

Initial Y-axis rotation of the camera, in degrees.

Type: number

Default: 0

pitch

Initial X-axis rotation of the camera, in degrees.
Should be a value from -90 to 90.

Type: number

Default: 0

initialZoom

Initial zoom value.
If number is given, positive value will make camera zoomed in and negative value will make camera zoomed out.
If object is given, it will fit model's bounding box's front / side face to the given ratio of the canvas height / width.
For example, { axis: "y", ratio: 0.5 } will set the zoom of the camera so that the height of the model to 50% of the height of the canvas.

Type: number

Default: 0

rotate

Options for the RotateControl.
If false is given, it will disable the rotate control.

Type: boolean | RotateControlOptions

Default: true

translate

Options for the TranslateControl.
If false is given, it will disable the translate control.

Type: boolean | TranslateControlOptions

Default: true

zoom

Options for the ZoomControl.
If false is given, it will disable the zoom control.

Type: boolean | ZoomControlOptions

Default: true

autoplay

Enable Y-axis rotation autoplay.
If true is given, it will enable autoplay with default values.

Type: boolean | AutoplayOptions

Default: true

scrollable

Enable browser scrolling with touch on the canvas area.
This will block the rotate(pitch) control if the user is currently scrolling.

Type: boolean

Default: true

wheelScrollable

Enable browser scrolling with mouse wheel on the canvas area.
This will block the zoom control with mouse wheel.

Type: boolean

Default: false

useGrabCursor

Enable CSS cursor: grab on the canvas element.
cursor: grabbing will be used on mouse click.

Type: boolean

Default: true

skybox

Source to the HDR texture image (RGBE), which will used as the scene environment map & background.
envmap will be ignored if this value is not null.

Type: string | null

Default: null

envmap

Source to the HDR texture image (RGBE), which will used as the scene environment map.

Type: string | null

Default: null

background

Color code / URL to a image to use as the background.
For transparent background, use null. (default value)
Can be enabled only when the skybox is null.

Type: number | string | null

Default: null

exposure

Exposure value of the HDR envmap/skybox image.

Type: number

Default: 1

shadow

Enable shadow below the model.
If true is given, it will enable shadow with the default options.
If false is given, it will disable the shadow.

Type: boolean | ShadowOptions

Default: true

skyboxBlur

Apply blur to the current skybox image.

Type: boolean

Default: false

toneMapping

This is used to approximate the appearance of high dynamic range (HDR) on the low dynamic range medium of a standard computer monitor or mobile device's screen.

Type: number

Default: THREE.LinearToneMapping

See:

useDefaultEnv

Whether to use generated default environment map.

Type: boolean

Default: true

defaultAnimationIndex

Index of the animation to play after the model is loaded

Type: number

Default: 0

animationRepeatMode

Repeat mode of the animator.
"one" will repeat single animation, and "all" will repeat all animations.
"none" will make animation to automatically paused on its last frame.

Type: string

Default: "one"

See:

annotationURL

An URL to the JSON file that has annotation informations.

Type: string | null

Default: null

annotationWrapper

An element or CSS selector of the annotation wrapper element.

Type: HTMLElement | string

Default: ".view3d-annotation-wrapper"

annotationSelector

CSS selector of the annotation elements inside the root element

Type: string

Default: ".view3d-annotation"

annotationBreakpoints

Breakpoints for the annotation opacity, mapped by degree between (camera-model center-annotation) as key.

Type: Record<number, number>

Default: { 165: 0, 135: 0.4, 0: 1 }

annotationAutoUnfocus

Whether to automatically unfocus annotation on user input

Type: boolean

Default: true

webAR

Options for the WebXR-based AR session.
If false is given, it will disable WebXR-based AR session.

Type: boolean | WebARSessionOptions

Default: true

sceneViewer

Options for the Google SceneViewer based AR session.
If false is given, it will disable SceneViewer based AR session.
See Official Page for the parameter details.

Type: boolean | SceneViewerSessionOptions

Default: true

quickLook

Options for the Apple AR Quick Look based AR session.
If false is given, it will disable AR Quick Look based AR session.

Type: boolean | QuickLookSessionOptions

Default: true

arPriority

Priority array for the AR sessions.
If the two sessions are available in one environment, the session listed earlier will be used first.
If the session name is not included in this priority array, that session will be ignored.
See AR_SESSION_TYPE

Type: Array<string>

Default: ["webAR", "sceneViewer", "quickLook"]

poster

Poster image that will be displayed before the 3D model is loaded.
If string URL is given, View3D will temporarily show poster image element with that url as src before the first model is loaded
If string CSS selector of DOM element inside view3d-wrapper or HTMLElement is given, View3D will remove that element after the first model is loaded

Type: string | HTMLElement | null

Default: null

canvasSelector

CSS Selector for the canvas element.

Type: string

Default: "canvas"

autoInit

readonly

Call init() automatically when creating View3D's instance
This option won't work if src is not given

Type: boolean

Default: true

autoResize

Whether to automatically call resize() when the canvas element's size is changed

Type: boolean

Default: true

useResizeObserver

Whether to listen ResizeObserver's event instead of Window's resize event when using the autoResize option

Type: boolean

Default: true

maintainSize

Whether to retain 3D model's visual size on canvas resize

Type: boolean

Default: false

maxDeltaTime

Maximum delta time in any given frame
This can prevent a long frame hitch / lag
The default value is 1/30(30 fps). Set this value to Infinity to disable

Type: number

Default: 1/30

Methods

destroy

Destroy View3D instance and remove all events attached to it

Returns: void

init

async

Initialize View3d & load 3D model

Returns: Promise<void>

Emits: View3D#event:load

resize

Resize View3D instance to fit current canvas size

Returns: void

load

async

Load a new 3D model and replace it with the current one

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
srcstring | Array<string>Source URL to fetch 3D model from

display

Display the given model in the canvas

Returns: void

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
modelModelA model to display
optionsobject✔️{}Options for displaying model
options.resetCameraboolean✔️trueReset camera to default pose

loadPlugins

async

Add new plugins to View3D

Returns: Promise<void>

  • A promise that resolves when all plugins are initialized
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
pluginsArray<View3DPlugin>Plugins to add

removePlugins

async

Remove plugins from View3D

Returns: Promise<void>

  • A promise that resolves when all plugins are removed
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
pluginsArray<View3DPlugin>Plugins to remove

screenshot

Take a screenshot of current rendered canvas image and download it

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
fileName✔️"screenshot"

Events

ready

An event that fires when View3D is initialized.
This will be called once after the first 3D model is loaded.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.

loadStart

An event that fires before loading a 3D model.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
srcstringA source URL of the model to load.
levelnumberA level of model when loading multiple models at once, an integer starting from 0.
maxLevelnumberMaximum level of models loading.

load

An event that fires when the 3D model is loaded but not displayed yet.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
modelModelA new model that loaded.
levelnumberA level of model when loading multiple models at once, an integer starting from 0.
maxLevelnumberMaximum level of models loading.

loadError

An event that fires when the 3D model fails to load / parse

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
levelnumberA level of model when loading multiple models at once, an integer starting from 0.
maxLevelnumberMaximum level of models loading.
errorErrorAn actual error instance that throwed when loading/parsing the model.

loadFinish

An event that fires when all assets in a single load sequence(i.e. View3D's init, load) are finished to load

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.

modelChange

An event that fires when the 3D Model is loaded and displayed on the canvas.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
modelModelA new model that displayed.

resize

An event that fires when View3D's resize() is called

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
widthnumberNew width of the canvas.
heightnumberNew height of the canvas.

beforeRender

An event that fires before rendering a frame.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
deltanumberTime passed from the previous render call, in milisecond.

afterRender

An event that fires after rendering a frame.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
deltanumberTime passed from the previous render call, in milisecond.

progress

An event that fires while assets are loading.
This extends the native ProgressEvent
To get total bytes, you should serve the 3D model with the Content-Length header.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
srcstringA source URL of the asset
lengthComputablebooleanA boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not.
loadednumberA 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing total by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead.
totalnumberA 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the Content-Length (the size of the body of the message), and doesn't include the headers and other overhead.

See:

inputStart

An event that fires at the start of every inputs

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
inputTypeINPUT_TYPEType of the input.

inputEnd

An event that fires at the end of every inputs

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
inputTypeINPUT_TYPEType of the input.

cameraChange

An event that fires on every camera movement

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
posePoseCurrent yaw, pitch, zoom, and pivot value
prevPosePosePrevious yaw, pitch, zoom, and pivot value

animationStart

An event that fires on animation start

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
indexnumberAn index of the animation.
clipTHREE.AnimationClipAn AnimationClip instance of the animation.
actionTHREE.AnimationActionAn AnimationAction instance of the animation.

animationLoop

An event that fires on single animation loop

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
indexnumberAn index of the animation.
clipTHREE.AnimationClipAn AnimationClip instance of the animation.
actionTHREE.AnimationActionAn AnimationAction instance of the animation.

animationFinished

An event that fires on animation finish

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
indexnumberAn index of the animation.
clipTHREE.AnimationClipAn AnimationClip instance of the animation.
actionTHREE.AnimationActionAn AnimationAction instance of the animation.

annotationFocus

An event that fires on annotation focus

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
annotationAnnotationAn instance of the annotation that triggered this event.

annotationUnfocus

An event that fires on annotation unfocus

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
annotationAnnotationAn instance of the annotation that triggered this event.

arStart

Emitted when WebARSession is started.
Not available in SceneViewer or AR Quick Look.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
sessionWebARSessionAn instance of WebARSession that triggered this event.

arEnd

Emitted when WebARSession is ended.
Not available in SceneViewer or AR Quick Look.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
sessionWebARSessionAn instance of WebARSession that triggered this event.

arModelPlaced

Emitted when model is placed in WebARSession.
Not available in SceneViewer or AR Quick Look.

Type: object

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.
sessionWebARSessionAn instance of WebARSession that triggered this event.
modelModelA model placed.

quickLookTap

An event that fires when user clicked the Apple pay button or custom action button

Type: Event

PROPERTYTYPEDESCRIPTION
typestringA type of the event.
targetView3DAn instance of View3D that triggered this event.

See: