Skip to content

Web viewer documentation

Welcome to Panoramax Web Viewer documentation ! It will help you through all phases of setup, run and develop on Panoramax JS pictures viewer.

Web viewer screenshots

Note

If at some point you're lost or need help, you can contact us through issues or by email.

Install the viewer

Many options are available for installing the viewer.

Panoramax viewer is available on NPM as @panoramax/web-viewer package.

npm install @panoramax/web-viewer

If you want the latest version (corresponding to the develop git branch), you can use the develop NPM dist-tag:

npm install @panoramax/web-viewer@develop

You can rely on various providers offering hosted NPM packages, for example JSDelivr.

<!-- You may use another version than 3.0.2, just change the release in URL -->
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@3.0.2/build/index.css" />
<script src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@3.0.2/build/index.js"></script>

You can install and use Panoramax web client based on code provided in this repository.

This library relies on Node.js 16, which should be installed on your computer. Then, you can build the library using these commands:

git clone https://gitlab.com/panoramax/clients/web-viewer.git
cd web-viewer/
npm install
npm build

Basic usage

First, you need to make sure everything is ready to create the viewer:

Make sure to have both JS and CSS code available in your HTML head part:

<!-- Change the actual path depending of where you installed the library -->
<link rel="stylesheet" type="text/css" href="web-viewer/build/index.css" />
<script src="web-viewer/build/index.js"></script>

And you also node a div somewhere in your HTML:

<div id="viewer" style="width: 500px; height: 300px"></div>

Then, the div is populated with this JavaScript code:

let myViewer = new Panoramax.Viewer(
    "viewer",  // Div ID
    "https://api.panoramax.xyz/api",  // STAC API endpoint
    { map: true }  // Viewer options
);

Make sure to import both JS and CSS in your code:

import Panoramax from '@panoramax/web-viewer';
import '@panoramax/web-viewer/build/index.css';

And have access in some way to a classic div HTML element:

const myDiv = document.getElementById("viewer");

Then, the div is populated with this JavaScript code:

let myViewer = new Panoramax.Viewer(
    myDiv,  // Div Element
    "https://api.panoramax.xyz/api",  // STAC API endpoint
    { map: true }  // Viewer options
);

Beyond classic viewer, other widgets are available and can be tested online:

Standalone-map

A simple map for showing coverage only.

var myMap = new Panoramax.StandaloneMap(
    "map",  // Div ID
    "https://api.panoramax.xyz/api"  // STAC API endpoint
);

Editor

A map and photo viewer, focused on a single sequence, for previewing edits made to it.

var myEditor = new Panoramax.Editor(
    "editor",  // Div ID
    "https://api.panoramax.xyz/api",  // STAC API endpoint
    {
        selectedSequence: "id-to-an-existing-sequence", // Sequence ID (mandatory)
        selectedPicture: "id-to-a-picture-in-this-sequence" // Picture ID (optional)
    }
);

User interface

Keyboard shortcuts

All interactions with the viewer can be done using the mouse, and some can be also done using keyboard.

  • Arrows (or 2/4/8/6 on keypad): move inside the picture, or move the map
  • Page up/down (or 3/9 on keypad) : go to next or previous picture in sequence
  • + / - : zoom picture or map in or out
  • * (or 5 on keypad) : move picture or map to its center
  • Home / ↖️ (or 7 on keypad) : switch map and picture as main shown component
  • End (or 1 on keypad) : hide minimized map or picture
  • Space : play or pause current sequence