Online 3D Viewer Engine

The Online 3D Viewer Engine allows you to easily embed 3D models on your website. Although the engine is primarily designed to serve the https://3dviewer.net website, it's possible to use it on any page to visualize 3D models.

Installation

The preferred way to install the engine is to get it as an NPM package. In some cases it's not possible, so a browser-ready bundle is available for download and add directly to a html file.

Install from NPM (preferred)

The engine is available as an NPM package called online-3d-viewer. The package itself is an ES6 module, so it can be used with several different bundlers.

You can install it by running the following command.

npm install online-3d-viewer

After installation you can import it like any other packages.

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

Download as browser-ready bundle

A bundle is available for every release. You need to download the zip file attached to the latest release. After that, copy the content of the zip file on your server, and include the main file on your site.

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

Usage

• Automatic initialization: Create some div elements on your site, and call a function that automatically initalizes all the viewers. This is the easiest way to use the library, but provides less flexibility.
• Initialization from code: Needs a bit more typing, but it's more flexible than the previous one.

External library handling

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 SetExternalLibLocation function. Make sure to call it before any other engine calls.

Automatic initialization

Create some elements anywhere on your page with the class name online-3d-viewer. You can create multiple elements with different parameters.

<div class="online_3d_viewer"
    style="width: 800px; height: 600px;"
    model="model.obj, model.mtl">
</div>

You can specify several attributes:

• model: Relative path to model files separated by comma.
• camera: Camera parameters (eye, center, up). 9 comma separated number values.
• defaultcolor: Default color for surfaces with no material. 3 comma separated number values for r, g, b.
• backgroundcolor: Canvas background color. 3 comma separated number values for r, g, b or four comma separated number values for r, g, b, a.
• edgesettings: Edge display settings. 5 comma separated values for 'on'/'off', r, g, b, threshold angle.
• environmentmap: Comma separated list of six images forming a texture box.
• environmentmapbg: Boolean ("true" or "false") to set the environment map as background.

After placing the elements, call the Init3DViewerElements function to initalize all the viewers. It must be called from the main JavaScript file outside of the onload event.

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

Initialization from code

You can also initalize the engine from code. In this case you can provide all the parameters as a JavaScript object. See the EmbeddedViewer documentation for more details.

window.addEventListener ('load', () => {
    // set the location of the external libraries
    OV.SetExternalLibLocation ('../libs');

    // 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, 2.0, 3.0),
            new OV.Coord3D (0.0, 0.0, 0.0),
            new OV.Coord3D (0.0, 1.0, 0.0),
            45.0
        ),
        backgroundColor : new OV.RGBAColor (255, 255, 255, 255),
        defaultColor : new OV.RGBColor (200, 200, 200),
        edgeSettings : new OV.EdgeSettings (false, new OV.RGBColor (0, 0, 0), 1),
        environmentSettings : new OV.EnvironmentSettings (
            [
                'assets/envmaps/fishermans_bastion/posx.jpg',
                'assets/envmaps/fishermans_bastion/negx.jpg',
                'assets/envmaps/fishermans_bastion/posy.jpg',
                'assets/envmaps/fishermans_bastion/negy.jpg',
                'assets/envmaps/fishermans_bastion/posz.jpg',
                'assets/envmaps/fishermans_bastion/negz.jpg'
            ],
            false
        )
    });

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