View3D

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

See:

• https://naver.github.io/egjs-component/

Properties

Methods

Events

VERSIONstatic
renderer
scene
camera
control
autoPlayer
model
animator
ar
annotation
rootEl
initialized
loadingContext
plugins
src
iosSrc
variant
dracoPath
ktxPath
meshoptPath
fixSkinnedBbox
fov
center
yaw
pitch
pivot
initialZoom
rotate
translate
zoom
autoplay
scrollable
wheelScrollable
useGrabCursor
ignoreCenterOnFit
skybox
envmap
background
exposure
shadow
skyboxBlur
toneMapping
useDefaultEnv
defaultAnimationIndex
animationRepeatMode
annotationURL
annotationWrapper
annotationSelector
annotationBreakpoints
annotationAutoUnfocus
webAR
sceneViewer
quickLook
arPriority
poster
canvasSelector
autoInit
autoResize
useResizeObserver
maintainSize
maxDeltaTime

destroy
init
resize
load
display
loadPlugins
removePlugins
screenshot

ready
loadStart
load
loadError
loadFinish
modelChange
resize
beforeRender
afterRender
progress
inputStart
inputEnd
cameraChange
animationStart
animationLoop
animationFinished
annotationFocus
annotationUnfocus
arStart
arEnd
arModelPlaced
quickLookTap

constructor

new View3D(root, options)

Creates new View3D instance.

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
root	string | HTMLElement			A root element or selector of it to initialize View3D
options	View3DOptions	✔️	{}	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

variant

Active material variant of the model.
Either can be index of the variant(number), or the name of the variant(string)
Changing this value will change the material of the model

Default: null

See:

• https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_variants/README.md

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

Specifies the center of the model.
If "auto" is given, it will use the center of the model's bounding box.
Else, you can use a number array as any world position.
Or, you can use a string array as a relative position to bounding box min/max. ex) ["0%", "100%", "50%"]
The difference to pivot is model's bounding box and center position will be shown on screen at every rotation angle.

Type: "auto" | Array<(number|string)>

Default: "auto"

yaw

Initial Y-axis rotation of the camera, in degrees.
Use view3D.camera.yaw instead if you want current yaw value.

Type: number

Default: 0

pitch

Initial X-axis rotation of the camera, in degrees.
Should be a value from -90 to 90.
Use view3D.camera.pitch instead if you want current pitch value.

Type: number

Default: 0

pivot

Initial origin point of rotation of the camera.
If "auto" is given, it will use model's center as pivot.
Else, you can use a number array as any world position.
Or, you can use a string array as a relative position to bounding box min/max. ex) ["0%", "100%", "50%"]
Use view3D.camera.pivot instead if you want current pivot value.

Type: "auto" | Array<(number|string)>

Default: "auto"

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

ignoreCenterOnFit

When camera.fit is called, View3D will adjust camera with the model so that the model is not clipped from any camera rotation by assuming center as origin of the rotation by default.
This will ignore that behavior by forcing model's bbox center as center of the rotation while fitting the camera to the model.

Type: boolean

Default: false

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:

• TONE_MAPPING

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:

• ANIMATION_REPEAT_MODE

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

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
src	string | Array<string>			Source URL to fetch 3D model from
options	object	✔️	{}	Options
options.iosSrc	string | null	✔️		Source URL to fetch 3D model in iOS AR Quick Look. usdz models are supported.

display

Display the given model in the canvas

Returns: void

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
model	Model			A model to display
options	object	✔️	{}	Options for displaying model
options.resetCamera	boolean	✔️	true	Reset camera to default pose

loadPlugins

async

Add new plugins to View3D

Returns: Promise<void>

• A promise that resolves when all plugins are initialized

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
plugins	Array<View3DPlugin>			Plugins to add

removePlugins

async

Remove plugins from View3D

Returns: Promise<void>

• A promise that resolves when all plugins are removed

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
plugins	Array<View3DPlugin>			Plugins to remove

screenshot

Take a screenshot of current rendered canvas image and download it

PARAMETER	TYPE	OPTIONAL	DEFAULT	DESCRIPTION
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

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.

loadStart

An event that fires before loading a 3D model.

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
src	string	A source URL of the model to load.
level	number	A level of model when loading multiple models at once, an integer starting from 0.
maxLevel	number	Maximum level of models loading.

load

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

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
model	Model	A new model that loaded.
level	number	A level of model when loading multiple models at once, an integer starting from 0.
maxLevel	number	Maximum level of models loading.

loadError

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

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
level	number	A level of model when loading multiple models at once, an integer starting from 0.
maxLevel	number	Maximum level of models loading.
error	Error	An 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

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An 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

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
model	Model	A new model that displayed.

resize

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

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
width	number	New width of the canvas.
height	number	New height of the canvas.

beforeRender

An event that fires before rendering a frame.

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
delta	number	Time passed from the previous render call, in milisecond.

afterRender

An event that fires after rendering a frame.

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
delta	number	Time 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

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
src	string	A source URL of the asset
lengthComputable	boolean	A 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.
loaded	number	A 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.
total	number	A 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:

• https://developer.mozilla.org/en-US/docs/Web/API/ProgressEvent

inputStart

An event that fires at the start of every inputs

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
inputType	INPUT_TYPE	Type of the input.

inputEnd

An event that fires at the end of every inputs

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
inputType	INPUT_TYPE	Type of the input.

cameraChange

An event that fires on every camera movement

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
pose	Pose	Current yaw, pitch, zoom, and pivot value
prevPose	Pose	Previous yaw, pitch, zoom, and pivot value

animationStart

An event that fires on animation start

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
index	number	An index of the animation.
clip	THREE.AnimationClip	An AnimationClip instance of the animation.
action	THREE.AnimationAction	An AnimationAction instance of the animation.

animationLoop

An event that fires on single animation loop

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
index	number	An index of the animation.
clip	THREE.AnimationClip	An AnimationClip instance of the animation.
action	THREE.AnimationAction	An AnimationAction instance of the animation.

animationFinished

An event that fires on animation finish

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
index	number	An index of the animation.
clip	THREE.AnimationClip	An AnimationClip instance of the animation.
action	THREE.AnimationAction	An AnimationAction instance of the animation.

annotationFocus

An event that fires on annotation focus

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
annotation	Annotation	An instance of the annotation that triggered this event.

annotationUnfocus

An event that fires on annotation unfocus

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
annotation	Annotation	An instance of the annotation that triggered this event.

arStart

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

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
session	WebARSession	An instance of WebARSession that triggered this event.

arEnd

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

Type: object

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
session	WebARSession	An 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

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.
session	WebARSession	An instance of WebARSession that triggered this event.
model	Model	A model placed.

quickLookTap

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

Type: Event

PROPERTY	TYPE	DESCRIPTION
type	string	A type of the event.
target	View3D	An instance of View3D that triggered this event.

See:

• https://developer.apple.com/documentation/arkit/adding_an_apple_pay_button_or_a_custom_action_in_ar_quick_look#3405186