Methods¶

The 270 Viewer opens itself up to a number of methods. These are available after the Viewer is done initialising, ie on onLoadComplete().

disableAutoRotate¶

Disables or enables rotation of the camera around the Asset.
Identical to enableAutoRotate(false).

el.disableAutoRotate(true, -2);

Parameters:

disabled:
- Type: Boolean
- Default: true
speed:
- Type: Float optional
- Default: previous value
  Use a negative value to rotate counter clockwise.

disableControls¶

Disallow or allow user interaction (zoom, pan, rotate).
Identical to enableControls(false).

el.disableControls(true);

Parameters:

disabled:
- Type: Boolean
- Default: true

disableDamping¶

Disable or enable camera weight movement.
Identical to enableDamping(false).

el.disableDamping(true, factor);

Parameters:

disabled:
- Type: Boolean
- Default: true
factor:
- Type: Float
- Default: 0.15

Factor is clamped between 0.001 and 1 to avoid erratic camera behavior

disablePan¶

Disallow or allow user camera panning.
Identical to enablePan(false).

Camera panning can be disorienting for users and is therefore not recommended to enable unless you really need it. Use resetPan() to restore original camera pan position.

el.disablePan(true);

Parameters:

disabled:
- Type: Boolean
- Default: true
verticalPan:
- Type: Boolean
- Default: false

disableRotate¶

Disallow or allow user camera rotation.
Identical to enableRotate(false).

el.disableRotate(true);

Parameters:

disabled:
- Type: Boolean
- Default: true

disableShadow¶

Hides or shows a shadow below the asset.
Identical to enableShadow(false).

el.disableShadow(true, false);

Parameters:

disabled:
- Type: Boolean
- Default: true
shadowSpace:
- Type: Boolean optional
- Default: previous value

disableZoom¶

Disallow or allow user camera zoom.
Identical to enableZoom(false).

el.disableZoom(true);

Parameters:

disabled:
- Type: Boolean
- Default: true

enableAutoRotate¶

Enable or disable rotation of the camera around the Asset.
Identical to disableAutoRotate(false).

el.enableAutoRotate(true, -2);

Parameters:

enabled:
- Type: Boolean
- Default: true
speed:
- Type: Float optional
- Default: previous value
  Use a negative value to rotate counter clockwise.

enableControls¶

Allow or disallow user interaction (zoom, pan, rotate).
Identical to disableControls(false).

el.enableControls(true);

Parameters:

enabled:
- Type: Boolean
- Default: true

enableDamping¶

Enable or disable camera weight movement.
Identical to disableDamping(false).

el.enableDamping(true, factor);

Parameters:

enabled:
- Type: Boolean
- Default: true
factor:
- Type: Float
- Default: 0.15

Factor is clamped between 0.001 and 1 to avoid erratic camera behavior

enablePan¶

Allow or disallow user camera panning.
Identical to disablePan(false).
Panning affects the camera target.

Camera panning can be disorienting for users and is therefore not recommended to enable unless you really need it. Use resetPan() to restore original camera pan position.

el.enablePan(true);

Parameters:

enabled:
- Type: Boolean
- Default: true
verticalPan:
- Type: Boolean
- Default: false

enableRotate¶

Allow or disallow user camera rotation.
Identical to disableRotate(false).

el.enableRotate(true);

Parameters:

enabled:
- Type: Boolean
- Default: true

enableShadow¶

Shows or hides a shadow below the asset.
Identical to disableShadow(false).

el.enableShadow(true, false);

Parameters:

enabled:
- Type: Boolean
- Default: true
shadowSpace:
- Type: Boolean optional
- Default: previous value

enableZoom¶

Allow or disallow user camera zoom.
Identical to disableZoom(false).

el.enableZoom(true);

Parameters:

enabled:
- Type: Boolean
- Default: true

getAnimation¶

Returns passed available animation state.

el.getAnimation('Walk');

Result:

{name: 'Walk', loop: true, reverse: false, state: 'stopped'},

getAnimations¶

Returns all available animations and their states.

el.getAnimations();

Result:

[
  {name: 'Walk', loop: true, reverse: false, state: 'stopped'},
  {name: 'Survey', loop: false, reverse: false, state: 'running'},
  {name: 'Jump', loop: false, reverse: false, state: 'paused'},
]

getAnimationNames¶

Returns all available animation names.

el.getAnimationNames();

Result:

['Walk', 'Survey', 'Jump']

getAmbientIntensity¶

Returns the current lighting's ambient intensity:

el.getAmbientIntensity()

Result:

'1'

getCameraPosition¶

Returns the current camera position as an object:

el.getCameraPosition()

Result:

{'zoom': 0-1, 'theta': 0-360, 'phi': 0-180}

getCameraTarget.¶

Returns the current camera target as an object:

el.getCameraTarget()

Result:

{'x': 0, 'y': 2, 'z': 0}

getEnvironmentIntensity¶

Returns the current environment's intensity:

el.getEnvironmentIntensity()

Result:

'0.9'

getGroup¶

Returns a specific Group by name, and its containing Objects' names.
A Group is a collection of associated Objects, as specified in the asset.

el.getGroup('Group')

Result:

{name: 'Group', objects: ['Base','Plane']}

Parameters:

name: Type: string
The name of the group to return

getGroups¶

Returns all loaded asset Groups and their contents. A Group is a collection of associated Objects, as specified in the asset.

el.getGroups()

Result:

[
  {name: 'Group', objects: ['Base','Plane']},
  {name: 'SecondGroup', objects: ['Cube, Mesh']}
]

getGroupNames¶

Returns the names of all available Groups. A Group is a collection of associated Objects, as specified in the asset.

el.getGroupNames()

Result:

['Group','SecondGroup']

getHorizontalRotation¶

Returns the current horizontal rotation limits:

el.getHorizontalRotation()

Result:

{min: -Infinity, max: Infinity}

getImage¶

Returns a snapshot of the Viewer as either an image or base64 string, with passed options.

el.getImage({
    size: {
        width: 200,
        height: 200
        },
    type: 'jpg',
    cameraPosition: {
        zoom: 1,
        theta: 75,
        phi: 35
    }
    cameraTarget: {
        x: 0,
        y: 1,
        z: 0
    }
})

Use el.getImage() without any options to get a snapshot as is, as a base64 string.

Parameters

options:
- Type: object
- keyvalues:
  - size: {width: int, height: int}
    The dimensions of the image, capped at 2048x2048. Defaults to current DOM size.
  - type: png|jpeg|jpg|webp
    Filetype of the returned image. Default is png
  - cameraPosition: {CameraPosition}
    Position of the camera for the snapshot. Defaults to el.getCameraPosition()
    
    Pass {preset: 'auto'} instead of {CameraPosition} to get a snapshot from the opening angle, regardless of user interaction.
  - cameraTarget: {CameraTarget}
    Position of the camera target for the snapshot. Defaults to el.getCameraTarget()
    
    Pass {preset: 'auto'} to set this to the original camera target, or {preset: 'defined'} to set this to the current camera target, regardless of user interaction.
  - background: hexstring
    The background color of the image. Defaults to current color.
  - transparent: Boolean
    Removes the background color completely. Ignored if type is jpeg|jpg. Default is false.
  - download: Boolean
    Prompts the user to download the image to disk. Default is false.
  - filename: string
    The filename of the downloaded image. Ignored if download is false. Default is 'snapshot'
  - scale: cover | contain
    How to scale the Viewer into the passed size. Default is contain.
    - contain scales the image as large as possible within its container without cropping or stretching the image.
    - cover scales the image (while preserving its ratio) to the smallest possible size to fill the container (that is: both its height and width completely cover the container), leaving no empty space.

getLighting¶

Returns the current lighting settings as an object:

el.getLighting()

Result:

{type: 'neutral', ambientIntensity: 0, sunIntensity: 0, exposure: 1, rotation: 0}

getLightingExposure¶

Returns the current lighting's exposure:

el.getLightingExposure()

Result:

'1.1'

getLightingRotation¶

Returns the current lighting's rotation in degrees:

el.getLightingRotation()

Result:

'45'

getLightingType¶

Returns the current lighting type:

el.getLightingType()

Result:

'neutral'

getObject¶

Returns a specific loaded asset objects by name.

el.getObject('Base')

Result:

{name: 'Base', texture: {width: 1024, height: 1024}, visible: true}

Parameters:

name: string
The name of the object to return.
Nested objects can be found via dotnotation: lunchbox.base.

getObjects¶

Returns all loaded asset objects in the passed groupname, and returns the name, texturesizes (if applicable) and visiblity, as an Array of Objects

el.getObjects(name)

Result:

[{name: 'Base', texture: {width: 1024, height: 1024}, visible: true}, {name: 'Plane', texture: null, visible: true}]

Parameters:

name: string optional
The name of the group to return the objects from.
Allows for nested groups: group1.group2.

getObjectNames¶

Returns the names of all loaded asset objects.

el.getObjectNames()

Result:

['Base','Plane']

getSettings¶

Returns the Viewer's settings as an object.

el.getSettings('state')

Result:

{ ambientIntensity: 0, autoplayAnimation: false, autorotate: false, autorotateSpeed: -2, background: '#ff0000', cameraPosition: '30,75', cameraZoomLevel: 0.39, container: 'div.viewer', customLightingData: {}, damping: true, forceLoad: false, horizontalRotation: '-Infinity,Infinity', lazyLoad: true, lighting: 'neutral', lightingExposure: 1, lightingRotation: 0, logo: true, loopAnimation: false, model: 'generic-polo-customisable', onCreate: () => {}, onLoadComplete: () => {}, onLoadFailure: () => {}, opacity: 0.2, pan: false, plugins: ['customiser'], reverseAnimation: false, rotate: true, rotateSpeed: 1, shadow: true, shadowBlur: 6, shadowDarkness: 1, shadowOpacity: 0.4, shadowSpace: true, sunIntensity: 0, verticalRotation: '0,180', zoom: true }

Parameters:

type
- Type: string
- Default: state
  The state to return. Options are:
  api: the settings as retrieved from the api
  init: the settings from when the viewer was created
  state: the current settings

getShadow¶

Returns the current shadow's settings as an object:

el.getShadow()

Result:

{visibile: true, spaced: false, darkness: 1, blur: 6, opacity: 0.4}

getShadowBlur¶

Returns the current shadow's blur setting:

el.getShadowBlur()

Result:

0.4

getShadowDarkness¶

Returns the current shadow's darkness setting:

el.getShadowDarkness()

Result:

getShadowOpacity¶

Returns the current shadow's opacity setting:

el.getShadowOpacity()

Result:

0.4

getSunIntensity¶

Returns the current lighting's directional light intensity:

el.getSunIntensity()

Result:

'1.2'

getTrueColors¶

Returns if trueColors is enabled

el.getTrueColors()

Result:

'true'

getVariant¶

Returns the current active variants, if applicable.

el.getVariant()

Result:

'leather'

getVariants¶

Returns the names of all loaded asset available variants, if any.

el.getVariants()

Result:

['leather','fabric']

getVerticalPan¶

Returns if vertical panning is enabled.

el.getVerticalPan()

Result:

true

getVerticalRotation¶

Returns the current vertical rotation limits:

el.getVerticalRotation()

Result:

{min: 45, max: 135}

getZoomRange¶

Returns the current zoomRange:

el.getZoomRange();

Result:

{min: 0.5, max: 1},

pauseAnimation¶

Pauses the Asset's passed animation. Use startAnimation() to resume the animation.
Passing no animation name pauses all running animations.

el.pauseAnimation({name: `Walk`});

Parameters:

name:
- Type: comma separated string
- Default: ''
  Comma separated list of animation names.

requestRender¶

Request a new frame to render if one wasn't queued already.

el.requestRender();

reset¶

Reset all Viewer settings back to the initially loaded state, either based on API settings or user initiated settings.

el.reset(false);

Parameters:

useAPI:
- Type: Boolean
- Default: false
  Whether to use the API (true) or .create directed (false) defaults.

resetPan¶

Reset the camera origin to the current {CameraTarget}. Useful after the user has panned away from the Asset when pan: true.

el.resetPan();

resizeViewer¶

Force resize of the viewer and ratio. This is done automatically when the Viewer's container's size changes.
All valid css is accepted.

el.resizeViewer({width: '500px', height: '550px'});

Parameters:

width:
- Type: String
- Default: implicit
height:
- Type: String
- Default: implicit

setAmbientIntensity¶

Sets the loaded lighting's minimal brightness.
Shorthand for setLighting({ambientIntensity: Float}).

As proper model visualisation is dependant on correct lighting it is recommended to only configure this when needed.

el.setAmbientIntensity(0.5);

Parameters:

intensity:
- Type: Float
- Default: implicit
  The lighting's minimal brightness.
  Passing nothing will reset the intensity to the loaded lighting's default value.

setAutoRotateSpeed¶

Sets the autorotate speed. Use a negative value for a clockwise rotation. Default is -2.

el.setAutoRotateSpeed(3);

Parameters:

speed: Float
The camera's rotation speed.

setBackground¶

Sets the Viewer's background to a solid color (css value), a gradient to infer depth (comma separated css values), or an image (url).

Note: When using a gradient or image, the opacity option is ignored.

el.setBackground('#ff0000', 0.5);

Parameters:

color:
- Type: css value | comma separated css values | url
  The color or image to set.
opacity:
- Type: Float optional
- Default: previous value
  The opacity of the background color ranging from 0 to 1, where 1 is fully opaque.
  This value is ignored if color is set to something different than a singular css value.

setCameraPosition¶

Move the camera to passed position.

el.setCameraPosition({
    zoom: 0.1,
    phi: 90,
    theta: 130
});

All parameters in the object are optional.

Omitting an option will default to the current value of that option. For example, el.setCameraPosition({zoom:0}) will zoom the camera out while maintaining phi and theta positions

Use presets to automatically set the phi and theta to a cardinal direction.

Parameters:

options
- Type: object
- keyvalues:
  - zoom: Float
    The zoom ratio ranging from 0 to 1, where 0 is furthest away. Defaults to current value.
  - phi: Float
    The vertical position of the camera in degrees, ranging from 0 to 180, where 0 is top. Defaults to current value.
    
    This value is limited by the current verticalRotation limits
  - theta: Float
    The horizontal position of the camera in degrees, ranging from 0 to 360. Defaults to current value.
    
    This value is limited by the current horizontalRotation limits
  - preset: string
    Set both horizontal and vertical position to match one of the cardinal options: top, bottom, left, right, front, back. Using a preset overrides the passed phi and theta values.
    
    This value is limited by the current horizontalRotation and verticalRotation limits

setCameraTarget¶

Move the camera's target to passed position. This is used as the Camera's focal point, affecting cameraPosition and zoomRange.

el.setCameraTarget({
    x: 0,
    y: 1.2,
    z: 0
});

Parameters:

options
- Type: object
- keyvalues:
  - x: Float
    The camera target's x (horizontal) position relative to the scene center, in meters.
  - y: Float
    The camera target's y (vertical) position relative to the scene center, in meters.
  - z: Float
    The camera target's z (depth) position relative to the scene center, in meters.
  - preset: auto
    Restore the original camera target. This overrides any passed x, y or z values.

setEnvironmentIntensity¶

Sets the HDRI's impact on the scene.
Shorthand for el.setLighting({intensity: 0.9})

el.setEnvironmentIntensity(0.9);

Parameters

intensity:
- Type: Float
- Default: implicit
  Impact of the loaded HDRI. A lower number results in a darker environment lighting and lesser reflections.

setHorizontalRotation¶

Limit the horizontal rotation of the camera.

el.setHorizontalRotation(20, 160);

Parameters

min: Float Number ranging from 0 to 360.
max: Float Number ranging from 0 to 360.

Passing free as either value will remove any limits

setLighting¶

Change the lighting preset in the Viewer, along with optional granular lighting controls.
Returns a promise.

el.setLighting({
  type: 'sunset',
  ambientIntensity: 1,
  sunIntensity: 0.4,
  environmentIntensity: 0.9,
  exposure: 1,
  rotation: 45
});

All parameters in the object are optional. Omitting an option will default to the current value of that option.

Parameters

preset:
- Type: String
- Default: traditional
  Options are neutral, neutral-2, cannon, city, courtyard, forest, interior, night, studio, sunrise, sunset, traditional, custom.
ambientIntensity:
- Type: Float optional
  The lighting's minimal brightness.
sunIntensity:
- Type: Float optional
  The lighting's directional light brightness.
environmentIntensity:
- Type: Float optional
  The HDRI's impact on the scene. Lower values result in darker environment lighting and lesser reflections.
exposure:
- Type: Float optional
  The lighting's exposure. Lower values result in darker overall lighting.
rotation:
- Type: Float optional
  The lighting's rotation in degrees.
customLightingData:
- Type: Object optional
  Adds a fully custom lighting setup to the custom slot. Refer to customLightingData options for a full data model example.
  This is an advanced feature and recommended to only pass if you know what you're doing.

As proper model visualisation is dependant on correct lighting it is recommended to only configure ambientIntensity, sunIntensity, exposure, rotation when needed.

setLightingType¶

Loads a lighting preset.
Shorthand for setLighting({type: preset}).

Loading a preset sets all other lighting options to the passed preset's defaults.

el.setLightingType('sunset');

Parameters

preset:
- Type: String
- Default: traditional
  Options are neutral, cannon, city, courtyard, forest, interior, night, studio, sunrise, sunset, traditional.

setLightingExposure¶

Sets the exposure of the loaded lighting.
Shorthand for setLighting({exposure: Float}).

el.setLightingExposure(1.2);

Parameters

exposure:
- Type: Float
- Default: implicit
  Exposure of the loaded lighting. A lower number results in a darker lighting.
  Passing nothing will reset the exposure to the loaded lighting's default value.

setLightingRotation¶

Sets the rotation of the loaded lighting.
Shorthand for setLighting({rotation: Float}).

el.setLightingRotation(45);

Parameters

exposure:
- Type: Float
- Default: implicit
  Rotation of the loaded lighting in degrees.
  Passing nothing will reset the rotation to the loaded lighting's default value.

setOpacity¶

Set the Viewer's background opacity without changing the background color.

el.setOpacity(1);

Parameters

opacity:
- Type: Float
  Range between 0 and 1, where 1 is fully opaque.

setRotationSpeed¶

Set the sensitivity of the camera rotation. A higher value results in a faster rotating camera.

el.setRotationSpeed(2);

Parameters

speed:
- Type: Float
- Default: options.rotateSpeed | 1

setShadow¶

Rerender a shadow with the passed properties. Returns a promise.

el.setShadow({visible: true, spaced: true, darkness: 4, opacity: 0.4, blur: 2});

Parameters

visible:
- Type: Boolean optional
- Default: current shadow's visibility
  Toggles visiblity of the shadow.
spaced:
- Type: Boolean optional
- Default: current shadow's space
  When true, adds space between the model, making the asset appear to float.
darkness:
- Type: Float optional
- Default: options.shadowDarkness
opacity:
- Type: Float optional
- Default: options.shadowOpacity
blur:
- Type: Float optional
- Default: options.shadowBlur

setShadowBlur¶

Set the blur of the shadow.
Shorthand for setShadow({blur: Float}).

el.setShadowBlur(0.4);

Parameters

blur:
- Type: Float
- Default: options.shadowBlur | 6

setShadowDarkness¶

Set the darkness of the shadow.
Shorthand for setShadow({darkness: Float}).

el.setShadowDarkness(2);

Parameters

darkness:
- Type: Float
- Default: options.shadowDarkness | 1

setShadowOpacity¶

Set the opacity of the shadow.
Shorthand for setShadow({opacity: Float}).

el.setShadowOpacity(1);

Parameters

opacity:
- Type: Float
- Default: options.shadowOpacity | 0.4

setSunIntensity¶

Sets the loaded lighting's minimal brightness. Shorthand for setLighting({sunIntensity: Float}).

As proper model visualisation is dependant on correct lighting it is recommended to only configure this when needed.

el.setSunIntensity(0.5);

Parameters:

intensity:
- Type: Float
- Default: implicit
  The lighting's directional light brightness.
  Passing nothing will reset the intensity to the loaded lighting's default value.

setTrueColors¶

Enables or disables trueColors

el.setTrueColors(true);

Parameters:

enabled:
- Type: Boolean
- Default: false

setVariant¶

Applies the passed variant to the loaded Asset and optionally renders a new frame. A variant is a preconfigured set of colors and/or materials, available in the loaded Asset.
Can be used as a promise.

el.setVariant({variant: 'leather', render: true})

Parameters:

variant: Type: string
The name of the desired variant. Use getVariants() to find the available variants.
render:
- Type: Boolean
- Default: true
  Immediately renders a new frame when true. If you are changing multiple items in the Viewer, consider setting this to false and call requestRender() manually to prevent unneeded frames.

setVerticalPan¶

Allow or disallow vertical (screenspace) panning.
When true, panning will be on the XY axis (up-down) rather than XZ (near-far).

el.setVerticalPan(true);

Parameters:

enabled:
- Type: Boolean
- Default: true

setVerticalRotation¶

Limit the vertical rotation of the camera.

el.setVerticalRotation(45,135);

Parameters

min: Float
Number ranging from 0 to 180.
max: Float
Number ranging from 0 to 180.

Passing free as either value will remove any limits

setZoomRange¶

Sets the relative minimum and maximum allowed zoom distance, based on the size of the object in the scene.

el.setZoomRange({min: 0.5, max: 1});

Parameters

min: Float
The miniumm allowed zoomdistance (how close the camera can get). This is limited by the max value.
- <1 allows for closer zooming, and >1 restricts how close the zoom can be.
max: Float
The maximum allowed zoomdistance (how far the camera can move away). This is limited by the min value.
- <1 restricts the maximum zoom, and >1 allows zooming out further.

Use a minimum value of 0 to allow the camera to zoom all the way into the center of the scene — useful for viewing interiors or very close details.
Use a maximum value greater than 1 (e.g. 2) to let the user zoom out much further than the default.
To restrict zooming in too close, use a minimum greater than 1 (e.g. 1.5).

startAnimation¶

Starts the passed animations.
Passing no animation name starts all available animations.

el.startAnimation({
  name: `Walk`,
  loop: true,
  reverse: false
});

Parameters

name:
- Type: comma separated string
- Default: ''
  Comma separated list of animation names.
loop:
- Type: Boolean
- Default: implicit
  Loops the animation(s). If nothing is passed it will default to the last passed state.
reverse:
- Type: Boolean
- Default: implicit
  Reverses the animation(s) when played. If nothing is passed it will default to the last passed state.

stopAnimation¶

Stops and rewinds the passed animations.
Passing no animation name stops all running animations.

el.stopAnimation({name: `Walk`});

Parameters:

name:
- Type: comma separated string
- Default: ''
  Comma separated list of animation names.