Embedded 3D viewer

Presenting 3D content interactively on the Web is still quite challenging nowadays and requires highly technical knowledge to make it accessible easily to a wide audience. At Sculpteo, we developped our own online 3D viewer to address this issue, using multiple technologies (Flash, Java, WebGL, raytracing) to ensure the 3D content could be delivered in any situation, without requiring the latest browsers or plugins.

Simple integration

The 3D viewer may be integrated to any external web page using a <iframe> tag, like so:

<iframe type="text/html" width="250" height="310" src="https://www.sculpteo.com/gallery/embed/23284182618746233915471266391450873072" frameborder="0" scrolling="no"></iframe>

This will create a 250x310 zone in the page where the design will appear, like so:

In this case, the design was already uploaded to Sculpteo’s website, and is identified by the number “23284182618746233915471266391450873072”. Several options that may be appended to the URL in the src attribute, to configure the appearance and behaviour of the viewer:


‘auto’ (default), ‘flash’, ‘java’, ‘webgl’ : Sets the 3D technology used for display of 3D content.


‘1’ (default) or ‘0’ (disabled) : Show/hide a small toolbar below the viewer to rotate the object by 90 degrees, switch to wireframe mode, toggle autorotation, etc…


xxxxxx (6 hexadecimal digits) : The HTML color for the background (without #), e.g. ‘ff0000’ for red.


‘’ (product page), ‘details’, ‘gallery’, ‘0’ : Action performed when the user clicks on the design, ‘0’ to disable.


‘window’ (default), ‘frame’, ‘box’ : Follow links either in the same page, in the same frame, or by overlaying a box containing the content.


‘false’, ‘true’ : Enable/disable autorotation on loading. The toolbar must be displayed for the model to rotate.

Advanced integration and scripting

To be able to display external files or script the viewer, a slightly more complex integration method must be used. First, you need to include a small bit of Javascript in the <head> section of your page:

<script src="https://www.sculpteo.com/js/sculpteo.widget.js" type="text/javascript"></script>

Then you may add a viewer anywhere you want in your web page by simply creating a <div> element with the “sculpteo_viewer” class. You may use CSS to position it and set its size, for example:

<div class="sculpteo_viewer" style="width: 250px; height: 310px; position: relative"></div>

The Javascript included in the header will automatically turn this <div> element into a viewer for you.

Options are passed to the viewer at initialization time by adding attributes to the <div>. For example, it is possible to directly display a 3D file hosted on your or any other web site by setting the ‘src’ attribute (provided the link is publicly reachable):

<div class="sculpteo_viewer" src="http://www.cc.gatech.edu/data_files/large_models/bunny.ply.gz" style="width: 250px; height: 310px; position: relative"></div>

We support a wide variety of formats such as OBJ, 3DS, VRML, STL, SKP, etc.. (see https://www.sculpteo.com/faq/en/help/#accepted-formats for the full list).

The other supported attributes are all the attributes supported in ‘simple integration’ are also supported as attributes to the <div> element. It is also possible to use a <a> element in which case the content depends on the ‘click’ attribute, and is displayed according to the ‘nav’ attribute.

Scripting is achieved by using the ‘sculpteo.viewer()’ javascript object. Several methods are provided via a fully asynchronous API:

load(String url,function onsuccess(), function onerror(Error e))

Load and display another 3D model.

Following calls of course need the viewer to be loaded to work :

setBackgroundColor(Number[0,255] r, Number[0,255] g, Number[0,255] b, function onsuccess(), function onerror(Error e))

Sets the viewer background color to r,g,b.


Enable or disable the solidity check control tool on your design.

e.g. : - sculpteo.viewer().setSolidity(true) : enable solidity check - sculpteo.viewer().setSolidity(false) : disable solidity check - sculpteo.viewer().setSolidity() : toggle solidity check


Change the material in the viewer.

e.g. : - sculpteo.viewer().setMaterial(“alumide”) : change material to alumide - sculpteo.viewer().setMaterial(“plastic_polished_red”) : change material to red polished plastic

An exaustive list of all the existing materials can be found here .

bind(String event, function onevent(…))

Listen to event, arguments of callback function are event-dependent.

unbind(String event)

Stop listening to event.

The following events are supported:


Triggered by camera rotation, returns current rotation as a quaternion.


Triggered by click on model, returns location and direction of click in object space.

For example, the following code will change the background of the viewer to a random color when user rotates the view:

<script type="text/javascript">
/* <![CDATA[ */
    sculpteo.viewer().bind("camera", function(w,x,y,z) {
        this.setBackgroundColor(parseInt(Math.random() * 255), parseInt(Math.random() * 255), parseInt(Math.random() * 255));
/* ]]> */


The following example illustrates the API presented above. A viewer frame is created, pointing to an external 3D resource, that is automatically downloaded and presented as interactive 3D content. Other 3D content may be displayed dynamically simply by copy/pasting the link to the 3D file and clicking the ‘load’ button. Rotating the design or clicking on it generates events that are logged, along with their arguments. Rotating the design also changes the background to a random color.

The code for this example is the following:

<!-- include the widget javascript -->
<script src="//www.sculpteo.com/js/sculpteo.widget.js" type="text/javascript"></script>

<!-- create a viewer pointing to an external resource, with no click action -->
<div class="sculpteo_viewer" src="http://www.cc.gatech.edu/data_files/large_models/bunny.ply.gz" click="0" style="width: 250px; height: 310px; float: left;"></div>

<div style="float: left; margin-left: 8px; width: 700px;">
    <!-- input for download URL -->
    <label>URL: (copy/paste link to 3D file)</label>
    <input type="text" id="download_url" value="http://www.cc.gatech.edu/data_files/large_models/bunny.ply.gz"></input>
    <input type="submit" value="load" onclick="load();"></input>
    <br />

    <!-- event console -->
    <div id="console" style="height: 200px; overflow: auto;"></div>
<br style="clear: both">

<!-- scripting -->
<script type="text/javascript">
/* <![CDATA[ */

    // function to load a new 3D model
    function load() {
        var url = document.getElementById("download_url").value;

    // function to log an event in the console
    function log(msg) {
        document.getElementById("console").innerHTML += msg + '<br>';

    // bind click event
    sculpteo.viewer().bind("click", function(x, y, z, dx, dy, dz) {
        log("click event x=" + x + ",y=" + y + ",z=" + z + ",dx=" + dx + ",dy=" + dy + ",dz=" + dz);

/* ]]> */
Prev: Embedding Sculpteo Web Components Next: Embedded 3D gallery

» webapi documentation » Embedding Sculpteo Web Components » Embedded 3D viewer

Last update: 1970-01-01 01:00 (CET)