Embedded viewer | Help

What is it?

The embedded viewer allows to display stereoscopic images with the viewer of Stereopix on your website. It is based on the integration of an iframe, like the YouTube player, but contrary to this one you can display your own images without publishing them on Stereopix^*. It is also compatible with webpages in private access without compromising their security.

^* Technical conditions apply, see the notice about CORS

Example

Let's illustrate the usage by an example of a common situation: showing a list of images.

HTML code

We will display these photos published on Flickr: Stereo Light Drawing (parallel view) published under the licence CC BY-NC-ND 2.0 by Jon Lewis, Making Fire (cross view) published under CC-BY 2.0 by ofir tirosh and this one (squeezed side-by-side) published under CC-NC 2.0 by Brian Westin. The result is:

As you might see in the source of this page, the HTML code is this one:

<script type="application/json" id="stereopix_json">
{
	"media": [
		{ "url": "https://live.staticflickr.com/106/278408302_41307d4a25_b.jpg" },
		{ "url": "https://live.staticflickr.com/4021/4543632327_668198daa0_o_d.jpg", "preset": "cross" },
		{ "url": "https://live.staticflickr.com/7696/17284050165_1c6bfab844_k_d.jpg", "preset": "hsbs" }
	]
}
</script>
<script type="text/javascript">
window.addEventListener('message', function(e) {
	if (e.origin == 'https://stereopix.net' && e.data.type == 'viewerReady') {
		var json = JSON.parse(document.getElementById('stereopix_json').textContent);
		e.source.postMessage({'stereopix_action': 'list_add_json', 'media': json}, 'https://stereopix.net');
	}
});
</script>
<iframe title="Stereoscopic (3D) photo viewer" 
style="width: 100%; height: 960px; max-height: 100vh; max-width: 100vw; border: 2px solid black; margin: 8px 0;" 
allowfullscreen="yes" allowvr="yes" allow="fullscreen;xr-spatial-tracking;accelerometer;gyroscope" 
src="https://stereopix.net/viewer:embed/"></iframe>

You can copy and paste it on your website for a first test.

Explanation of the snippet

Understanding this piece of code is not necessary to use it, but here are its main parts.

The big picture is that we use an iframe to show the viewer, together with some code to detect incoming message saying that the viewer is ready and to send the list of media back. The list is isolated to its own block for readability.

The first block is a JSON document enclosed in script tag of type application/json, which describes the list. The whole syntax for advanced usage is described in another help page, but we can recognise a list in square brackets made of objects in curly brackets representing the media. Each object has an URL and a preset (full-size parallel side-by-side if not set) which configures the viewer for the input file.

The second block is a javascript code which listens to the messages sent to the window and detects the viewerReady one sent by stereopix. When this message is received, the JSON document is parsed and sent to the viewer. If this document is malformed, an error will be emitted in the console of the browser and the viewer will stay with an empty list.

Finally, we are using the iframe element which allows to include a webpage inside another page. The attribute title is used for accessibility. The style defines the width (100% of the available space) and height (960 pixels) of the iframe, but these values will be limited by the size of the viewport so that it will always be displayable in its entirety (note that the viewer adapts itself to the available space inside the iframe, with a minimal size though). It also defines a border and clearance margin around the iframe for aesthetics. Some permissions should be explicitly given to access some sensors and display controls, and are thus defined afterwards. Then, the attribute src gives the path to the loaded page, which is the address of the embedded viewer.

Your images

To display your own images, you can use the precedent snippet and change the JSON document. Notice that the addresses have to form a valid URL and the images should be served in HTTPS with appropriate CORS headers (see afterwards). The objects describing the media should be separated by a comma, but the last one should not have a trailing comma: it is a common mistake that invalidates the document.

Important notice about CORS

If you are sure that the address you provided is referring to an actual image file (not a webpage) and that it is served in HTTPS, but have a loading error, the browser may block it.

Cross-origin resource sharing (CORS) is a security mechanism implemented in modern browsers. In particular, when a site wants to load a resource from another domain, the browser asks the server serving the resource if it is allowed. Therefore, you have to use a server which actively allows your images to be loaded externally (image hosting services, such as Flickr or Imgur, allow it).

See some solutions to enable it on your server in the advanced usage page.

Advanced usage

After this example, you may want to describe a more complex list of photos, get information from the viewer or send commands to it. These are advanced usages described in a dedicated page.

See Advanced usage page.