Usage
Distribution
The ShapeDiver 3D viewer v2 is available via the following storage locations:
- direct access: https://shapediverviewer.s3.amazonaws.com/v2/2.MINOR.PATCH/FILE, or
- CDN: https://viewer.shapediver.com/v2/2.MINOR.PATCH/FILE
Version numbers (2.MINOR.PATCH) follow the rules of SemVer.
The following files are available:
sdv.min.js: minified viewersdv.concat.min.js: minified viewer concatenated with external dependencies (Three.js, axios, verb-nurbs)sdv_reflector.min.js: helper script which allows to reflect the API v2 between different browser windows, typically from an iframe to its parent window
JavaScript Namespace
Including the viewer JavaScript file defines the namespace SDVApp.
<script defer src="https://viewer.shapediver.com/v2/2.3.0/sdv.concat.min.js"></script>Basic usage
Please refer to SDVApp.ParametricViewer for a documentation of available settings of the SDVApp.ParametricViewer constructor.
Direct embedding - including UI
Give it a try: Direct embedding example
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
<title>ShapeDiver Viewer v2</title>
<!-- ShapeDiver Viewer -->
<script defer src="https://viewer.shapediver.com/v2/2.3.0/sdv.concat.min.js"></script>
<link rel='stylesheet' type='text/css' href='https://viewer.shapediver.com/v2/2.3.0/sdv.css'>
<!-- ShapeDiver Viewer Controls Dependencies - these will be replaced by UIkit in the near future -->
<link rel='stylesheet' type='text/css' href='https://viewer.shapediver.com/external/font-awesome.min.css'>
<script src='https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js' integrity='sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44=' crossorigin='anonymous'></script>
<script defer src='https://viewer.shapediver.com/external/spectrum.js'></script>
<script defer src='https://viewer.shapediver.com/external/Sortable.js'></script>
<!-- ShapeDiver Viewer Export Modal Dialog Dependencies -->
<!-- UIkit CSS -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.0-rc.15/css/uikit.min.css" />
<!-- UIkit JS -->
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.0-rc.15/js/uikit.min.js"></script>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.0-rc.15/js/uikit-icons.min.js"></script>
</head>
<body>
<!-- ShapeDiver Viewer Main Container -->
<div id='sdv-container' class='shapediver-container-flex shapediver-container-fullsize'>
<!-- ShapeDiver Viewer Settings Controls Container -->
<div id='sdv-container-settings' class='shapediver-settings-flex' style='display: none;'></div>
<!-- ShapeDiver Viewer Viewport Container -->
<div class='shapediver-viewport-flex'>
<div id='sdv-container-viewport' class='shapediver-container-fullsize' style='opacity: 0;'
logginglevel=0
messagelogginglevel=2
>
</div>
<!-- The loading icon will be created here -->
</div>
<!-- ShapeDiver Viewer Parameter Controls Container -->
<div id='sdv-container-controls' class='shapediver-controls-flex' style='display: none;'></div>
</div>
<script>
// ShapeDiver Viewer Initialisation
var initSdvApp = function(/*event*/) {
// settings can be defined here or as attributes of the viewport container
// settings defined here take precedence
let settings = {
ticket: 'TICKET_FOR_YOUR_MODEL',
modelViewUrl : 'eu-central-1', // or 'us-east-1' or address of your own ShapeDiver model view server
};
// provide global access to the ShapeDiver Viewer API returned by the constructor
window.api = new SDVApp.ParametricViewer(settings);
};
// there is a slight chance that loading has been completed already
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initSdvApp, false);
} else {
initSdvApp();
}
</script>
</body>
</html>iframe embedding
Give it a try: iframe embedding example
We provide a script for reflecting the API v2 to the iframe's parent window. This is done by translating all API calls to and from messages between the browser Window objects, see Window.postMessage.
After loading the example shown below, try to type api=SDVReflector.get('api') in your browser console to see the magic
and get access to an API v2 object without the need to think about
Window.postMessage.
Please note that all synchronous functions of the API v2 become asynchronous due to the messaging which is happening
in the background, e.g. api.parameters.get() becomes api.parameters.getAsync().
In case of iframe embedding you can pass settings to the constructor of SDVApp.ParametricViewer by means of query string parameters.
The example below shows settings modelViewUrl and ticket being passed in this way.
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="google" value="notranslate">
<title>ShapeDiver Viewer v2 - iframe test</title>
<!-- ShapeDiver Viewer API reflector, sets the global variable SDVReflector -->
<script src="https://viewer.shapediver.com/v2/2.3.0/sdv_reflector.min.js"></script>
</head>
<body>
<!-- Uncomment this script if you want to see messages received from the iframe in the browser console -->
<!--
<script>
window.addEventListener('message', console.log, false);
</script>
-->
<!-- Uncomment this script if you want to trigger some actions once the ShapeDiver Viewer has been loaded -->
<!--
<script>
window.addEventListener('message', function(event) {
if ( event.data && typeof event.data === 'object' ) {
if ( event.data.type === 'sdv-ViewerLoaded' ) {
console.log('ShapeDiver Viewer initialisation finished', event.data);
sdapi = SDVReflector.get('api');
} else if ( event.data.type === 'sdv-CommPluginLoaded' ) {
console.log('ShapeDiver CommPlugin successfully loaded', event.data);
sdapi.parameters.getAsync().then( function(result) {
console.log('Available model parameters', result.data);
});
}
}
}, false);
</script>
-->
<!-- Refer to the settings of the SDVApp.ParametricViewer constructor to find out which query string parameters can be used -->
<iframe id='sdv-iframe'
width="640" height="480"
src="https://viewer.shapediver.com/v2/2.3.0/iframe/remote.html?modelViewUrl=eu-central-1&ticket=TICKET_FOR_YOUR_MODEL"
referrerpolicy="origin"
allowfullscreen
scrolling="no"
style="overflow-x: hidden; overflow-y: hidden; border-width: 0;"
>
<p>Your browser does not support iframes.</p>
</iframe>
</body>
</html>As the iframe loads and the viewer initializes, the following messages will be sent to notify you about the progress:
{type: 'sdv-DOMContentLoaded'}: The DOM content of the iframe has been completely loaded, initialisation of the viewer has begun.{type: 'sdv-ViewerLoaded'}: The initialisation of the viewer has finished, it's safe to callapi=SDVReflector.get('api')to retrieve the reflected API v2 object.
Will only be sent if a ticket is specified when calling SDVApp.ParametricViewer:
{type: 'sdv-CommPluginLoaded'}: The CommPlugin which was created bySDVApp.ParametricViewerwas successfully loaded.{type: 'sdv-CommPluginFailed'}: The CommPlugin which was created bySDVApp.ParametricViewerfailed to loaded.
Advanced usage
Direct embedding - minimal
To be documented
Deferred loading of geometry
To be documented
Loading of additional CommPlugins
To be documented