Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IViewportApi

The api for viewports.

Viewports are created by calling the createViewport method.

Each viewport has corresponding cameras and lights.

Additionally, there are various other settings to adjust the behavior and rendering of the viewport.

By default a new viewport displays the complete scene tree. Viewports can be excluded from displaying geometry for specific sessions by using the excludeViewports property of ISessionApi.

Hierarchy

  • IViewportApi

Index

Properties

animations: {}

A dictionary of all animations that are currently present in the parts of the scene tree relevant to this viewport.

Type declaration

arRotation: vec3

The rotation factor that is used when exporting the scene for AR (Augmented Reality). The unit system used by AR is meter.

see

arScale

see

arTranslation

see

arRotation

arScale: vec3

The scaling factor that is used when exporting the scene for AR (Augmented Reality).

The unit system used by AR is meter, therefore this scaling factor needs to be chosen such that scene coordinates are transformed to meters.

see

arScale

see

arTranslation

see

arRotation

arTranslation: vec3

The translation factor that is used when exporting the scene for AR (Augmented Reality). The unit system used by AR is meter.

see

arScale

see

arTranslation

see

arRotation

automaticColorAdjustment: boolean

Option to enable / disable the automatic color space adaption. This converts all color inputs to the chosen outputEncoding. (default: true)

automaticResizing: boolean

Option to enable / disable the automatic resizing of the viewport to changes of the canvas. (default: true)

beautyRenderBlendingDuration: number

The duration used by the beauty rendering to blend in (milliseconds).

beautyRenderDelay: number

The delay after which the beauty rendering starts (milliseconds).

camera: null | ICameraApi

The current camera.

cameras: {}

The cameras of the viewport.

Type declaration

canvas: HTMLCanvasElement

The canvas that is used to render the viewport.

clearAlpha: number

The clear alpha value of the viewport. Use this to influence the background appearance of the viewport.

clearColor: Color

The clear color value of the viewport. Use this to influence the background appearance of the viewport.

defaultMaterialColor: Color

The color that is used when no material is specified. (default: #199b9b)

enableAR: boolean

Option to enable / disable the AR (Augmented Reality) functionality for this viewport. (default: true) This setting is used purely for UI purposes, it does not have any influence on the viewport itself.

environmentMap: string | string[]

The environment map used by the viewport. You can either use the HDR maps at ENVIRONMENT_MAP or the LDR legacy maps at ENVIRONMENT_MAP_CUBE. Additionally, you can specify your own maps. For HDR maps, provide a link to a .hdr file, for LDR provide the folder where the six cube map images are located.

environmentMapAsBackground: boolean

Option to set the environment map as the background of the viewport. (default: false)

environmentMapBlurriness: number

The amount of which the environment map is blurred. (default: 0)

environmentMapForUnlitMaterials: boolean

Option to set the environment map for unlit materials. (default: false) For unlit materials, which use the three.js MeshBasicMaterial, per default we don't set the environment map to keep the colors as realistic as possible.

environmentMapIntensity: number

Scales how much the environment map effects the materials. (default: 1)

environmentMapResolution: string

The environment map resolution that is used for preset cube maps.

see

environmentMap

environmentMapRotation: quat

The rotation quaternion that is used on the environment map. (default: [0,0,0,1])

gridColor: Color

The color of the grid.

gridVisibility: boolean

Option to enable / disable the grid. (default: true)

groundPlaneColor: Color

The color of the ground plane.

groundPlaneShadowColor: Color

The color of the ground plane shadow.

groundPlaneShadowVisibility: boolean

Option to enable / disable the ground plane shadow. (default: false)

groundPlaneVisibility: boolean

Option to enable / disable the ground plane. (default: true)

id: string

The id of the viewport.

lightScene: null | ILightSceneApi

The current light scene.

lightScenes: {}

The light scenes of the viewport.

Type declaration

lights: boolean

Option to enable / disable lights. (default: true)

maximumRenderingSize: { height: number; width: number }

The maximum size of the renderings. The renderings will be upscaled to the actual resolution if these values are lower than the resolution of the canvas. This setting exists, as for higher resolutions the performance can drop due to the rendering effort. (default: { width: 1920, height: 1080 })

Type declaration

  • height: number
  • width: number
outputEncoding: TEXTURE_ENCODING

The encoding that is used for the output texture. (default: TEXTURE_ENCODING.SRGB) This is the texture that is rendered to the screen.

see

textureEncoding

physicallyCorrectLights: boolean

Option to enable / disable the physically correct lights. (default: true)

pointSize: number

The point size that is used for rendering point data.

postProcessing: IPostProcessingApi

The [post processing api]{@link IPostProcessingApi} of the viewport.

Note: The post-processing API is still WIP. Breaking changes are to be expected.

shadows: boolean

Option to enable / disable rendering of shadows. (default: true)

show: boolean

Option to show / hide the viewport. This will disable rendering, and hide the canvas behind the logo. Using this setting especially makes sense with VISIBILITY_MODE.MANUAL where you can decide at what point you first want to show the scene.

showStatistics: boolean

Option to show / hide rendering statistics overlayed to the viewport. (default: false)

softShadows: boolean

Option if the soft shadows should be rendered when the camera is not moving. (default: true)

textureEncoding: TEXTURE_ENCODING

The encoding that is used for textures. (default: TEXTURE_ENCODING.SRGB)

see

outputEncoding

threeJsCoreObjects: { camera: Camera; renderer: WebGLRenderer; scene: Scene }

Some of the three.js core objects so that you are free to use and adjust them yourself.

Please note that the camera will be replaced when you change it via the API. The same goes for the children in the scene tree that are auto-generated and properties of the renderer that are adjusted internally.

Type declaration

  • camera: Camera
  • renderer: WebGLRenderer
  • scene: Scene
toneMapping: TONE_MAPPING

The tone mapping that is used. (default: TONE_MAPPING.NONE)

toneMappingExposure: number

The intensity of the tone mapping.

The type of rendering of this viewport.

visualizeAttributes: undefined | ((overview: ISDTFOverview, itemData?: ISDTFItemData) => ISDTFAttributeVisualizationData)

A possibility to visualize the attributes of the scene in any way you want. Please have a look at the help desk documentation for more information.

Provide a callback that transforms a ISDTFItemData to a ISDTFAttributeVisualizationData. The ISDTFOverview provides general information like min and max values for numbers or the available options for strings.

sessionSettingsId?: string

Optional identifier of the session to be used for loading / persisting settings of the viewport. This is ignored in case sessionSettingsMode is not SESSION_SETTINGS_MODE.MANUAL.

sessionSettingsMode?: SESSION_SETTINGS_MODE

Allows to control which session to use for loading / persisting settings of the viewport. (default: SESSION_SETTINGS_MODE.FIRST).

see

sessionSettingsId

Methods

  • Add an event listener that receives all canvas events.

    Parameters

    Returns string

  • Add a flag for this viewport. Adding/removing flags allows to influence the render loop. If you want to stop this again call removeFlag with the returned token.

    Parameters

    Returns string

  • applyViewportSettings(settings: ISettings, sections?: { ar?: boolean; camera?: boolean; environment?: boolean; general?: boolean; light?: boolean; postprocessing?: boolean; scene?: boolean }): Promise<void>
  • Apply the settings of a viewport manually. You can get the settings via getViewportSettings. You can choose which sections will be applied, by default they are all set to false.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • settings: ISettings
    • Optional sections: { ar?: boolean; camera?: boolean; environment?: boolean; general?: boolean; light?: boolean; postprocessing?: boolean; scene?: boolean }
      • Optional ar?: boolean
      • Optional camera?: boolean
      • Optional environment?: boolean
      • Optional general?: boolean
      • Optional light?: boolean
      • Optional postprocessing?: boolean
      • Optional scene?: boolean

    Returns Promise<void>

  • assignCamera(id: string): boolean
  • Assign the camera with the specified id to the viewport. This will make the given camera the current one.

    see

    camera

    Parameters

    • id: string

      The id of the camera.

    Returns boolean

  • assignLightScene(id: string): boolean
  • Assign the light scene with the current id to the viewport. This will make the given light scene the current one.

    see

    lightScene

    Parameters

    • id: string

      The id of the light scene.

    Returns boolean

  • close(): Promise<void>
  • Closes the viewport and will remove all traces of the canvas element.

    Returns Promise<void>

  • continueRendering(): void
  • Continue the rendering of the scene. Can be used with pauseRendering to continue/pause the rendering at will.

    see

    pauseRendering

    Returns void

  • convert3Dto2D(p: vec3): { client: vec2; container: vec2; hidden: boolean; page: vec2 }
  • Convert the given 3D position to different 2D coordinates of HTML Elements. If the point is hidden by geometry, the hidden property will be set to true.

    The returned coordinates all have their origin in the top left corner of the element. For container, the position is relative to the canvas element. For client, the position is relative to the canvas element, including the results of getBoundingClientRect. For page, the position is relative to the whole page.

    Parameters

    • p: vec3

    Returns { client: vec2; container: vec2; hidden: boolean; page: vec2 }

    • client: vec2
    • container: vec2
    • hidden: boolean
    • page: vec2
  • convertToGlTF(node?: ITreeNode): Promise<Blob>
  • Convert the current visible elements (or just from the node specified) in the viewport into a glTF file.

    The gound plane and grid will not be included, as well as additionally added data that was added to the scene other than through a GeometryData property.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional node: ITreeNode

      Optional node to provide to transform into a glTF. (default: scene tree)

    Returns Promise<Blob>

  • createArSessionLink(node?: ITreeNode, qrCode?: boolean, fallbackUrl?: string): Promise<string>
  • Create a link / QRCode that can be opened by mobile devices to display in AR.

    As some models might have a different scale then the AR apps (meters), the scaling can be chosen freely arScale.

    Internally, the scene will first be converted into a glTF. This glTF will be uploaded to our backend and converted into a USDZ to be able to start AR on iOS and Android.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional node: ITreeNode

      Optional node to display in AR. (default: scene tree)

    • Optional qrCode: boolean

      Option to receive a QR Code instead of a link (default: true)

    • Optional fallbackUrl: string

      Optional fallback url if the link was opened by an unsupported device or an error occurred. If none was provided, the user will be redirected to shapediver.com/app

    Returns Promise<string>

  • createLightScene(properties?: { name?: string; standard?: boolean }): ILightSceneApi
  • Create a new light scene. An id can be provided. If not, a unique id will be created. If the standard option is chosen, the default lights will be added from the start.

    Parameters

    • Optional properties: { name?: string; standard?: boolean }
      • Optional name?: string
      • Optional standard?: boolean

        The option to add the standard lights.

    Returns ILightSceneApi

  • Create an orthographic camera. An id can be provided. If not, a unique id will be created.

    Parameters

    • Optional id: string

      The id of the camera.

    Returns IOrthographicCameraApi

  • Create a perspective camera. An id can be provided. If not, a unique id will be created.

    Parameters

    • Optional id: string

      The id of the camera.

    Returns IPerspectiveCameraApi

  • Create the ISDTFOverview for the provided node. If no node was provided, the scene root is used instead.

    Parameters

    • node: ITreeNode

      The node for which the overview is created.

    Returns ISDTFOverview

  • displayErrorMessage(message: string): void
  • Display an error message on the canvas.

    Parameters

    • message: string

      The message to display.

    Returns void

  • getEnvironmentMapImageUrl(): string
  • Get the complete URL of the current environment map, if it is a single file. This can be used in case environmentMap is set to a preset environment map.

    Returns string

  • getScreenshot(type?: string, quality?: number): string
  • Create a screenshot for the requested type and options.

    Parameters

    • Optional type: string

      The type as string, default is 'image/png'.

    • Optional quality: number

      The quality of the screenshot, default is 1.

    Returns string

  • getViewportSettings(): ISettings
  • Get the current settings object of this viewport. Can be re-applied at a later point with applyViewportSettings.

    Returns ISettings

  • isMobileDeviceWithoutBrowserARSupport(): boolean
  • Determines if the current device is a mobile device (or tablet) but still doesn't support to view the content in AR.

    Can be used in combination with viewableInAR to display a warning to use a different browser if viewableInAR is false and isMobileDeviceWithoutBrowserARSupport is true.

    Reasons for that can be:

    • Firefox on Android
    • Instagram in App browser

    Returns boolean

  • mouseEventToRay(event: MouseEvent): { direction: vec3; origin: vec3 }
  • Calculate the ray that is created by the mouse event and the camera.

    see

    touchToRay

    see

    touchEventToRay

    Parameters

    • event: MouseEvent

    Returns { direction: vec3; origin: vec3 }

    • direction: vec3
    • origin: vec3
  • pauseRendering(): void
  • From the provided origin and direction, trace the ray through the scene. The intersections with GeometryData will be returned including the corresponding nodes, sorted by their smallest distance.

    If you want to raytrace the scene from an interaction with the the canvas, please use mouseEventToRay, touchEventToRay or touchToRay to create a ray first.

    An optional root node can be provided to intersect. Per default, the whole scene tree will be intersected.

    Parameters

    • origin: vec3
    • direction: vec3
    • Optional root: ITreeNode

    Returns { distance: number; node: ITreeNode; data?: IGeometryData }[]

  • removeCamera(id: string): boolean
  • Remove the camera with the specified id and destroys it. If you remove the current active camera, the rendering will be stopped until a new camera is assigned.

    Parameters

    • id: string

      The id of the camera.

    Returns boolean

  • removeCanvasEventListener(token: string): boolean
  • Remove an event listener that received all canvas events.

    Parameters

    Returns boolean

  • removeFlag(token: string): boolean
  • Removes the registered flag. Adding/removing flags allows to influence the render loop.

    Parameters

    • token: string

      The token that was returned by addFlag.

    Returns boolean

  • removeLightScene(id: string): boolean
  • Remove the light scene with the specified id. If you remove the current active light scene, no lights will be shown.

    Parameters

    • id: string

      The id of the light scene.

    Returns boolean

  • render(): void
  • Manual call to render the scene.

    Returns void

  • resetToDefaultCameras(): void
  • Delete all current cameras and create our 7 default cameras.

    A perspective one (default) and 6 orthographic ones (top, bottom, left, right, front, back).

    Returns void

  • resize(width: number, height: number): void
  • If the automaticResizing is option is set to false, this function resizes the Viewport.

    Parameters

    • width: number

      The new width of the Viewport.

    • height: number

      The new height of the Viewport.

    Returns void

  • restrictEventListeners(allowedListeners: { contextmenu?: boolean; keydown?: boolean; mousedown?: boolean; mousemove?: boolean; mouseout?: boolean; mouseup?: boolean; mousewheel?: boolean; touchcancel?: boolean; touchend?: boolean; touchmove?: boolean; touchstart?: boolean }): void
  • Restrict events. This can be used to disable events for a viewport.

    Example use case: If you don't want to allow mouse wheel events for a specific viewport so that users can scroll past the viewport.

    Be aware that this might cause some issues with the the camera controls if the mouse / touch events are disabled only partially.

    Parameters

    • allowedListeners: { contextmenu?: boolean; keydown?: boolean; mousedown?: boolean; mousemove?: boolean; mouseout?: boolean; mouseup?: boolean; mousewheel?: boolean; touchcancel?: boolean; touchend?: boolean; touchmove?: boolean; touchstart?: boolean }
      • Optional contextmenu?: boolean
      • Optional keydown?: boolean
      • Optional mousedown?: boolean
      • Optional mousemove?: boolean
      • Optional mouseout?: boolean
      • Optional mouseup?: boolean
      • Optional mousewheel?: boolean
      • Optional touchcancel?: boolean
      • Optional touchend?: boolean
      • Optional touchmove?: boolean
      • Optional touchstart?: boolean

    Returns void

  • touchEventToRay(event: TouchEvent): { direction: vec3; origin: vec3 }
  • Create the ray that is created by the touch event and the camera.

    see

    mouseEventToRay

    see

    touchToRay

    Parameters

    • event: TouchEvent

    Returns { direction: vec3; origin: vec3 }

    • direction: vec3
    • origin: vec3
  • touchToRay(event: Touch): { direction: vec3; origin: vec3 }
  • Create the ray that is created by the touch and the camera.

    see

    mouseEventToRay

    see

    touchEventToRay

    Parameters

    • event: Touch

    Returns { direction: vec3; origin: vec3 }

    • direction: vec3
    • origin: vec3
  • update(): void
  • Update the viewport with the current changes of the complete scene tree. This carries out preparations for rendering. Call it after doing direct changes to the scene tree.

    Returns void

  • updateEnvironmentGeometry(): void
  • Update the position of the environment geometry (grid, groundplane, etc) to the current viewport bounding box. Internally, this functions is called whenever a session is customized, but if you manually change parts of the scene, it might get necessary to call this function. Make sure to call update before, to apply the last changes.

    Returns void

  • Update the viewport with the current changes of given scene tree node and its descendants. This carries out preparations for rendering. Call it after doing direct changes to the scene tree.

    Parameters

    Returns void

  • updateNodeTransformation(node: ITreeNode): void
  • Update the viewport with the current changes in transformation of given scene tree node and its descendants. This carries out preparations for rendering. Call it after doing direct changes to the scene tree transformations.

    Parameters

    Returns void

  • View the current scene in AR.

    Please check first if the device supports the viewing of models in AR, see viewableInAR. As some models might have a different scale then the AR apps (meters), the scaling can be chosen freely arScale.

    Internally, the scene will first be converted into a glTF. This glTF will be uploaded to our backend to be able to start AR.

    throws

    {@type ShapeDiverViewerError}

    Parameters

    • Optional node: ITreeNode

      Optional node to display in AR. (default: scene tree)

    Returns Promise<void>

  • viewableInAR(): boolean