Embedded viewer (advanced) | Help

Note: This page explains some advanced usage of the viewer. An other page presents a simple example.

Repository of examples
Use a list of media
Get feedback from the viewer
Send commands to the viewer
CORS management

Repository of examples

To help to understand the advanced features of the viewer, a repository of examples is available.

You can see them in action on https://stereopix.github.io/viewer-examples/ and inspect the sources of the pages to analyse how they work. They are good practical complements to this reference page.

Use a list of media

When you want to add several media in the viewer, you need to create a JSON object describing the list. This object will be passed dynamically to the viewer.

General strcuture

The root of the JSON document is an object (curly brackets) with the following keys:

media contains an array (square brackets) of objects describing each medium as described in the next subsection.
meta is optional. If set, it contains an object with optional properties:
- initial is a number (0 if not set) which defines which index of the media array to display if the list was previously empty.
- json_next is a string (empty if not set) which defines the URL to load to get the next part of the list when split in several parts. It is loaded dynamically when the user reaches the end.
- json_prev is a string (empty if not set) which defines the URL to load to get the previous part of the list when split in several parts. It is loaded dynamically when the user reaches the beginning.
- url_base is a string (empty if not set) which will serve as base URL for the addresses of the media.
userdata is optional. It is not used by the viewer itself, but you can add your own additional data without interfering with a future version. It can be useful if you use this file for other purposes as well.

Other keys are ignored, but reserved for future usage.

Medium description

Each medium in the list is described by an object with the following optional keys:

url_base is a string (empty if not set) which will serve as base URL for the addresses of this medium.
url is a string or an array of strings which contains the URL of the medium. When in an array, the adresses will be used as a list of fallbacks if the medium cannot be loaded or decoded. When the URL ends with .webp, the viewer automatically skips the entry if the browser does not support this format.
In addition, this key can be a array of arrays of strings. This particular case allows to specify several variants to be selected in a drop-down menu on the overlay. In each internal array, the strings represent the name (first element), the URL (second element) and fallback URLs (other elements).
thumbnail is a string or an array of strings (optional) which contains the URL of the thumbnail.
swapped is a boolean (false if not set) indicating that the left and right views are swapped.
phantogram is a boolean (false if not set) indicating that the medium is a phantogram. It will be displayed horizontally when possible.
video is a boolean (false if not set) indicating that the medium is a video.
preset is a string ("sbs" if not set) indicating the kind of input file. It can be mono (regular 2D), sbs or lr (full-size parallel side-by-side), rl or cross (full-size crossed side-by-side), hsbs, sbsq, hlr or lrq (squeezed parallel side-by-side), hrl, rlq, hcross or crossq (squeezed crossed side-by-side), tab, ab or ou (full-size over-under), htab, tabq, hab, abq, hou or ouq (squeezed over-under), lrl (combined left-right-left image), rlr (combined right-left-right image).
projection is a string ("rectilinear" when not set) describing the projection to use. It can be rectilinear (used by most cameras), vr180 (equirectangular for hemisphere) or vr360 (equirectangular for sphere).
roi is an array of 8 numbers (defined by preset if not set). It defines the location of the views inside the image. It is in the form [XL, YL, WL, HL, XR, YR, WR, HR] with suffixes L and R for left and right, X and Y the coordinate of the top-left corder, W and H are the dimensions. These numbers are expressed in percentage of width and height of the original image (e.g. XR set at 0.5 and YR set at 0 means that the top-left corner of the right view is at the top center of the image). The preset key should allow to ignore this parameter in most cases.
ratio_factor is a number (defined by preset if not set). It gives the factor applied to the ratio of the image to get the ratio of the views in some projections (e.g. when two rectilinear 16:9 views are packed side-by-side, the ratio of the image is 32:9 and thus this key is 0.5). The preset key should allow to ignore this parameter in most cases.
anchor is a string (randomly generated if not set) defining a name that can be used with the goto command.
extra is a special key (null if not set) that is not used by the viewer itself, but will be passed to your page when the corresponding medium is displayed.
userdata is not used by the viewer itself and not transmitted to the parent page, but you can add your own additional data without interfering with a future version. It can be useful if you use this JSON for other purposes as well.

Other keys are ignored, but reserved for future usage.

Real-world JSON example

This example uses images hosted on Flickr. The extra fields could be used to fill a description zone in the page embedding the iframe for example.

{
	"media": [
		{
			"url": "https://live.staticflickr.com/4076/5039658762_ac47bce3e6_h.jpg",
			"extra": {
				"url": "https://www.flickr.com/photos/jonolave/5039658762/",
				"licence": "CC BY 2.0",
				"author": "Jon Olav Eikenes",
				"title": "Stereoscopic tree"
			}
		},
		{
			"swapped": true,
			"url": "https://live.staticflickr.com/3407/3639496556_b74e2690f5_k.jpg",
			"extra": {
				"url": "https://www.flickr.com/photos/ofirtirosh/3639496556/",
				"licence": "CC BY 2.0",
				"author": "ofir tirosh",
				"title": "light sticks"
			}
		},
		{
			"url": [
				"https://live.staticflickr.com/7130/8151585543_4133a16b52_4k.jpg",
				"https://live.staticflickr.com/7130/8151585543_7f10d61127_k.jpg"
			],
			"extra": {
				"url": "https://www.flickr.com/photos/hanuska/8151585543/",
				"licence": "CC BY SA 2.0",
				"author": "Dushan Hanuska",
				"title": "Upside down again"
			}
		},
		{
			"swapped": false,
			"url": "https://live.staticflickr.com/3539/3795231236_b9a8b74630_b.jpg",
			"extra": {
				"url": "https://www.flickr.com/photos/parallel_yoshing/3795231236/",
				"licence": "CC BY NC 2.0",
				"author": "Hiroshi Yoshinaga",
				"title": "piggy bank ぶたさん貯金箱 (parallel 3D)"
			}
		},
		{
			"url": "https://live.staticflickr.com/65535/49757330292_9f86a02e68_o_d.jpg",
			"projection": "vr180",
			"extra": {
				"url": "https://www.flickr.com/photos/karmicdesigns/49757330292/",
				"licence": "CC BY NC ND 2.0",
				"author": "Chris",
				"title": "sd2"
			}
		}
	],
	"meta": {
		"initial": 2
	}
}

Send to the viewer

This JSON document can be sent to the viewer by script with the list_add_json action detailed later in the page.

Get feedback from the viewer

When opened in an iframe or a popup, the player sends messages to the other page. These messages can be received by listening the message event of the window:

window.addEventListener('message', function(e) {
	if (e.origin == 'https://stereopix.net') {
		console.log(e.data);
	}
});

The message e.data is an object whose key type gives the type of report (see following subsections) and other keys convey additional data when present.

viewerReady

A message of type viewerReady is emitted when the viewer is ready to interact.

listChanged

A message of type listChanged is emitted when the list is modified. It can be sent when a new list is loaded or when a new part of a split list is added.

The following data are also present:

position, an integer giving the position of the current item in the new list.
list_length, an integer giving the length of the list.
list_partial, a boolean true when the list is split in several parts and all parts were not loaded yet.
extra, a copy of the extra field of the current item provided in the JSON document when available (or null otherwise).

mediumChanged

A message of type mediumChanged is emitted when the medium changes, before it is actually loaded. It can be emitted multiple times for the same item, when an alternative URL is loaded for example.

The following data are also present:

position, an integer giving the position of the current item in the list.
anchor, a string identifying the current position in the list. This identifier is kept when a new medium is added to the list and can be used in the goto command.
extra, a copy of the extra field provided in the JSON document when available (or null otherwise).

fullscreen

A message of type fullscreen is emitted when the fullscreen status changes.

The following data are also present:

enabled, a boolean telling whether the player is in fullscreen or not.
error, a boolean optionnaly added when the viewer cannot open in fullscreen.

Send commands to the viewer

The viewer can receive commands. They are passed with the postMessage mechanism and should be objects with a stereopix_action key describing the action to do (see following subsections) and optionally with additional parameters.

For example, assuming you added the id="stereopix_viewer" attribute to the targeted iframe:

const viewer = window.frames['stereopix_viewer'].contentWindow;
viewer.postMessage({'stereopix_action': 'next'}, 'https://stereopix.net');

This action changes the image to the next item of the list.

This action changes the image to the previous item of the list.

goto

This action changes the image to a particular item in the list.

position can be:
- an integer defining the new position to reach
- a string when an anchor name is used

swap

This action swaps left and right views of the current image.

list_clear

This action clears the list of media.

list_add_json

This action adds one medium or several media from JSON depending on the key used.

For one medium, the key is medium:

medium is an object describing one medium.
before is an optional boolean (false if not set). When true, the medium is inserted at the beginning of the list.

For several media, the key is media:

media is an object describing a whole list.
before is an optional boolean (false if not set). When true, the media are inserted at the beginning of the list.

If both medium and media are used, the command is ignored.

CORS management

There are different ways to enable CORS depending on your environment.

In short, in the case of the simple GET requests made by the viewer, the browser sends a Origin header in its HTTP request notifying from which domain comes the request, and checks the presence of Access-Control-Allow-Origin: https://stereopix.net or Access-Control-Allow-Origin: * header in the answer. If this header is absent or does not correspond to the origin domain, the resource is not accessible and thus cannot be displayed in the viewer.

S3 buckets or similar

Most services hosting files with an S3-compatible bucket engine have an interface to manage CORS headers when serving your files and an HTTPS address (a second address in their domain if you used a custom domain name). See the documentation of your provider to enable it.

.htaccess for Apache

The Apache web server can be configured locally with .htaccess files. You can add the following lines in this special file to add the HTTP header to some files. Here the files are selected by extension, but you can change the Files directive or the value of the header according to your needs.

<Files ~ "\.(webp|jpe?g|png|json)$">
  Header add Access-Control-Allow-Origin "*"
</Files>

By server script

If your server allows it, you can add a script that will send the wanted header and copy the content of the file.

For example with the popular PHP language, you can use the following script. In addition to sending the wanted header, it includes some instructions for the cache control logic of the client browser to reduce the pressure on the server.

<?php
$defaultfile = 'list.json';
$accepted_extensions = array('webp', 'jpg', 'jpeg', 'png', 'json');
$accepted_origins = array('https://stereopix.net'); // or $accepted_origins = '*';

$file = pathinfo($_GET['f'] ?? $defaultfile, PATHINFO_BASENAME); // Allow only files from this directory /!\
if (in_array(pathinfo($file, PATHINFO_EXTENSION), $accepted_extensions) && file_exists($file)) {
        $lastModified = filemtime($file);
        $etag = md5($lastModified);
        $ifModifiedSince = strtotime($_SERVER['HTTP_IF_MODIFIED_SINCE'] ?? false);
        $etagHeader = trim($_SERVER['HTTP_IF_NONE_MATCH'] ?? '');
        $origin = $_SERVER['HTTP_ORIGIN'] ?? false;
        if ($origin) {
                header('Vary: Origin');
                if ($accepted_origins == '*')
                        header('Access-Control-Allow-Origin: *');
                else if (in_array($origin, $accepted_origins))
                        header('Access-Control-Allow-Origin: '.$origin);
                else
                        header($_SERVER['SERVER_PROTOCOL'].' 403 Forbidden') && exit;
        }
        header('Last-Modified: '.gmdate('D, d M Y H:i:s', $lastModified).' GMT');
        header('Etag: '.$etag);
        header('Cache-Control: public');
        if ($etagHeader == $etag || $ifModifiedSince == $lastModified) {
                header($_SERVER['SERVER_PROTOCOL'].' 304 Not Modified');
        } else {
                header('Content-Type: '.mime_content_type($file));
                header('Content-Length: '.filesize($file));
                readfile($file);
        }
} else {
        header($_SERVER['SERVER_PROTOCOL'].' 404 Not Found');
}
?>