Skip to content

Embed the Viewer Engine

Jump to bottom Edit New page
Viktor Kovacs edited this page May 10, 2022 · 33 revisions

It's possible to embed the Online 3D Viewer Engine in your website to visualize 3D models.

Basics

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 te 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

  1. Download and extract the zip file for the latest release (o3dv_<version>.zip).
  2. Include the three.min.js and the o3dv.min.js files on your site.
<script type="text/javascript" src="three.min.js"></script>
<script type="text/javascript" src="o3dv.min.js"></script>
  1. Call the initialization code anywhere on the site.
<script type='text/javascript'>
    OV.Init3DViewerElements ();
</script>

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>

Full code:

<!DOCTYPE html>
<html>

<head>
    <meta http-equiv="content-type" content="text/html;charset=utf-8">
    <meta name="viewport" content="width=device-width, user-scalable=no">

    <title>Online 3D Viewer</title>

    <script type="text/javascript" src="three.min.js"></script>
    <script type="text/javascript" src="o3dv.min.js"></script>
    <script type='text/javascript'>
        OV.Init3DViewerElements ();
    </script>
</head>

<body>
    <div class="online_3d_viewer"
        style="width: 800px; height: 600px;"
        model="testfiles/obj/hundred_cubes.obj,testfiles/obj/hundred_cubes.mtl"
        camera="3,1,2,0,0,0,0,0,1"
        defaultcolor="200,0,0"
        backgroundcolor="200,200,200"
        edgesettings="on,0,0,0,1">
    </div>
</body>

</html>

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

This is available from version 0.8.3 only.

  1. Download and extract the zip file for the latest release (o3dv_<version>.zip).
  2. Include the three.min.js and the o3dv.min.js files on your site.
<script type="text/javascript" src="three.min.js"></script>
<script type="text/javascript" src="o3dv.min.js"></script>
  1. Create an OV.EmbeddedViewer instance anywhere it's needed.

Example:

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.LoadModelFromUrls ([
        '../../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/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');
Add a custom footer
Add a custom sidebar
Clone this wiki locally