Skip to main content

Viewer API Getting Started

In this section we will explore adding a simple 3d viewer on an HTML page, adding required plugins, loading a 3d asset with all scene settings.

note

Checkout the Introduction and Installation pages before starting.

Create a canvas​

First add a HTML Canvas element on the page.

<canvas id="my-canvas"></canvas>

The canvas can be styled independently with css or js to set the width and the height.

Import the Library​

In a typescript or javascript file, the viewer can be imported directly.

import {ViewerApp} from "webgi";

See the Installation page for more details.

Create the viewer.​

ViewerApp can be initialised with just the canvas.

async function intialize3D(){
    const viewer = new ViewerApp({
      canvas: document.getElementById('main-canvas') as HTMLCanvasElement,
    })
    // add plugins and load a model. More below.
}

If it is not required to handle the creation of the canvas. the viewer can be instanced by passing the container, a canvas will be created that fills the container completely. For example to create a full screen viewer, pass the body as the container:

const viewer = new ViewerApp({
    container: document.body,
})

Some optional options are available that control the base rendering pipeline.

const viewer = new ViewerApp({
    canvas,
    useRgbm: true, // Use HDR RGBM Pipeline. false will use HDR Half float pipeline
    useGBufferDepth: true, // Uses depth prepass for faster rendering, has z-fighting in some cases.
    isAntialiased: false, // Uses multi-sample render target. (only for extreme cases)
})

Add plugins​

ViewerApp comes with a library of plugins to interact with the 3D scene, add new features and functionality. Check the Plugins page for more.

We can start by adding the AssetManagerPlugin to load our 3d model.

The AssetManagerPlugin manages download, management, caching, parsing, loading and adding of assets to the scene. Extensions can be added for loading different file types and also to export textures, materials and GLTF models. Check the Asset Management page for more

First import the plugin.

// All plugins can be imported from `webgi`
import {
    ViewerApp,
    AssetManagerPlugin, TonemapPlugin, // ...others
} from "webgi";

Then add to the viewer.

const manager = new AssetManagerPlugin();
await viewer.addPlugin(manager);

or simply

const  manager = await viewer.addPlugin(AssetManagerPlugin);

More plugins can be added to enhance the quality and add features.

await viewer.addPlugin(TonemapPlugin);
await viewer.addPlugin(PickingPlugin);
await viewer.addPlugin(GroundPlugin);
await viewer.addPlugin(DiamondPlugin);

After adding all the plugins call:

viewer.renderer.refreshPipeline()
note

refreshPipeline sets up the render and post processing pipeline based on what plugins are added. It must be called once after adding the plugins.

Load 3D Assets​

We can use the manager to load 3d models, environment maps, materials and images. To load a hosted glb file from a URL

const options = {autoScale: false}
const assets = await manager.addFromPath("https://demo-assets.pixotronics.com/pixo/gltf/cube.glb", options)

This downloads the file and adds it to the scene.

Note that the addFromPath function returns an array, this is because it's possible to load a zip or any other container file which can contain multiple assets. There are several function signature in the asset manager for different cases.

Many options are available to control how assets are imported, processed and added to the scene. Check the page on Asset Management or the AssetImporter docs for more.

All models are automatically scaled and centered, it's possible to disable this by passing in the necessary options.

For simple use-cases, the recommended way is to use our sandbox editor to export a compressed glb file. This adds the background, environment map and all the plugin, scene settings which are automatically loaded at this step.

For other cases it's possible to load an HDR environment map with the manager and setting it to the current scene.

const envMap = await manager.importer!.importSinglePath<ITexture&Texture>("https://demo-assets.pixotronics.com/pixo/hdr/p360-01.hdr")
viewer.scene.environment = envMap || null;

Summary​

This is the complete code which will display a simple cube in the canvas with a custom environment map. It can also be found in the webgi-sample repository along with other samples.

import {
  ViewerApp,
  AssetManagerPlugin, TonemapPlugin
} from "webgi"

async function intialize3D(){
    // Create a viewer for the canvas
    const viewer = new ViewerApp({
      canvas: document.getElementById('main-canvas') as HTMLCanvasElement,
    })

    // Add plugins
    const manager = await viewer.addPlugin(AssetManagerPlugin)
    await viewer.addPlugin(TonemapPlugin)

    viewer.renderer.refreshPipeline()

    // Load the assets at once.
    await Promise.all([
      viewer.scene.setEnvironment(await manager.importer!.importSingle({path:'https://demo-assets.pixotronics.com/pixo/hdr/p360-01.hdr'}))
      manager.addAsset({path:'https://demo-assets.pixotronics.com/pixo/gltf/cube.glb'})
    ])
}

Next steps​

The next tutorial covers the basics of the plugin system in webgi and provides an intro to some core plugins that are used to get photorealistic rendering.