Embed the Viewer Engine

This document guides you through the process of using the Online 3D Viewer engine in your website. You can check some working examples here: Online3DViewerExamples.

How to get the engine?

Browser-ready bundle

A browser-ready bundle is available in every release. Just download and extract the zip file attached to the latest release, and include the o3dv.min.js file on your site.

<script type="text/javascript" src="o3dv.min.js"></script>

NPM package

The engine is also available as an NPM package called online-3d-viewer. This is an ES6 module that can be used with the import command.

You can install the package by the following command:

npm install online-3d-viewer

After this you must import it where you need it.

import * as OV from 'online-3d-viewer';

How to embed the engine?

The embedding code needs a parent element (preferably a div). The viewer canvas will be automatically resized to the size of the parent element. On window resize the size will be automatically adjusted, but if you resize the parent element manually, you have to call the resize function of the viewer.

There are two ways to embed the engine:

• Use the provided helper functions, and define everything as attributes of the parent element. This is the easiest way to embed the engine.
• Do the initialization by code. This needs some scripting, but you will have more freedom.

Embed with helper function

Call the initialization code anywhere on the site.

OV.SetExternalLibLocation ('libs'); // tell the engine where to find the libs folder
OV.Init3DViewerElements (); // init all viewers on the page

And that's it. If you create elements with the class name online_3d_viewer, the models will be automatically loaded. For example:

<div class="online_3d_viewer"
    style="width: 800px; height: 600px;"
    model="models/my_model.3ds,models/my_texture.png">
</div>

You can specify model parameters:

• model: Relative path to model files separated with commas.
• camera: Camera parameters (eye, center, up) separated with commas.
• defaultcolor: Default color (r, g, b) for surfaces with no material. (Before version 0.7.16 it was called color.)
• backgroundcolor: Canvas background color (r, g, b). (Before version 0.7.16 it was called background.)
• edgesettings: Edge display settings ('on'/'off', r, g, b, threshold angle). (From version 0.8.2.)
• environmentmap: Comma separated list of six images forming a texture box. (From version 0.7.17.)

Embed with coding

Create an OV.EmbeddedViewer instance anywhere it's needed.

Example:

// tell the engine where to find the libs folder
OV.SetExternalLibLocation ('libs');

window.addEventListener ('load', () => {
    // get the parent element of the viewer
    let parentDiv = document.getElementById ('viewer');

    // initialize the viewer with the parent element and some parameters
    let viewer = new OV.EmbeddedViewer (parentDiv, {
        camera : new OV.Camera (
            new OV.Coord3D (-1.5, -3.0, 2.0),
            new OV.Coord3D (0.0, 0.0, 0.0),
            new OV.Coord3D (0.0, 0.0, 1.0)
        ),
        backgroundColor : new OV.Color (255, 255, 255),
        defaultColor : new OV.Color (200, 200, 200),
        edgeSettings : {
            showEdges : false,
            edgeColor : new OV.Color (0, 0, 0),
            edgeThreshold : 1
        },
        environmentMap : [
            '../website/assets/envmaps/grayclouds/posx.jpg',
            '../website/assets/envmaps/grayclouds/negx.jpg',
            '../website/assets/envmaps/grayclouds/posy.jpg',
            '../website/assets/envmaps/grayclouds/negy.jpg',
            '../website/assets/envmaps/grayclouds/posz.jpg',
            '../website/assets/envmaps/grayclouds/negz.jpg'
        ]
        onModelLoaded : () => {
            let model = viewer.GetModel ();
            // do something with the model
        }
    });

    // load a model providing model urls
    viewer.LoadModelFromUrlList ([
        '../../test/testfiles/obj/hundred_cubes.obj',
        '../../test/testfiles/obj/hundred_cubes.mtl'
    ]);
});

After the initailization you can access the OV.Viewer instance by calling the GetViewer function of the OV.EmbeddedViewer instance. With the viewer instance you can access all the functionalities of the viewer.

Since currently no detailed documentation is available, you may check the code of the OV.Viewer class for the available functions: https://github.com/kovacsv/Online3DViewer/blob/master/source/engine/viewer/viewer.js

Using the provided external libraries

Some of the importers are implemented using external libraries. These are found in the libs folder of the package. To make these libraries available, you have to tell the engine where to find them. The location of the external libraries can be set with the OV.SetExternalLibLocation call. Make sure to call it before any other engine calls. For example:

OV.SetExternalLibLocation ('libs');