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.

Getting started template

Public template to create a project with parcel bundler and typescript: https://github.com/pixotronics/webgi-vanilla-starter
This has webgi module included with types. Make sure to set the latest version in package.json.

Click the Use this template button on github to create a new repo.

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

We provide ES6 module for use in custom apps. For common use-cases we also provide pre-built files for the websites (see quickstart)
The library can be imported in HTML/JS directly in any modern supported browser as a ES6 module.

<script type="module">
import {ViewerApp} from "https://dist.pixotronics.com/webgi/runtime/bundle-<version>.js";
</script>

While this is fine for small experiments, it’s better to use the library in a typescript/javascript project as a npm library and use a bundler to build custom bundles for your target platforms.

If using a bundler, add the dependency in pacakge.json

{
	"devDependecies": {
	"webgi": "https://storage.googleapis.com/dist.pixotronics.com/webgi/runtime/bundle-<version>.tgz",  
	"@types/webgi": "https://storage.googleapis.com/dist.pixotronics.com/webgi/runtime/bundle-types-<version>.tgz",
	...
	}
}

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

import {ViewerApp} from "webgi";

The webgi-vanilla-starter repository is an example of using parcel with typescript to bundle an example for the browser. More plugins and configuration can be added to parcel to target old browsers and to integrate UI libraries.
You may use any other bundler like webpack, rollup or esbuild

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, fails 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 wiki 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 create a compressed glb file. This adds the environment map and all the plugin, scene settings which are automatically loaded at this step.

Check the Readme for the link to the sandbox editor.

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>("https://demo-assets.pixotronics.com/pixo/hdr/p360-01.hdr")
viewer.scene.setEnvironment(envMap);

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.

---

Back to home