@panoramax/web-viewer 3.2.3 → 4.0.0

package/docs/04_Advanced_examples.md

@@ -1,216 +0,0 @@
-# Advanced examples
-
-On this page, you will discover many examples on how to do practical things, like changing the map tiles, or adding custom buttons.
-
-## Change map background style
-
-The viewer can be configured to use a different map background than the default one. By default, an OpenStreetMap France classic style if offered. Changing the style is done by passing a `style` parameter on viewer setup. It should follow the [MapLibre Style specification](https://maplibre.org/maplibre-style-spec) and be passed as an object, or an URL to such style:
-
-```js
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		style: "https://my.tiles.provider/basic.json",
-		map: { startWide: true }
-	}
-);
-```
-
-Note that the viewer also support PMTiles (for a simpler tile hosting), so your style file can contain vector source defined like this:
-
-```json
-{
-  "sources": {
-    "protomaps": {
-        "type": "vector",
-        "url": "pmtiles://https://example.com/example.pmtiles",
-    }
-  }
-}
-```
-
-If you need to customize the received JSON style for compatibility issues, this can be done by passing an object instead of a string. Here is an example based on IGN map styling, which needs some parameter to be changed:
-
-```js
-fetch("https://wxs.ign.fr/essentiels/static/vectorTiles/styles/PLAN.IGN/standard.json")
-.then(res => res.json())
-.then(style => {
-  // Patch tms scheme to xyz to make it compatible for Maplibre GL JS
-  style.sources.plan_ign.scheme = 'xyz';
-  style.sources.plan_ign.attribution = 'Données cartographiques : © IGN';
-
-  var viewer = new Panoramax.Viewer(
-    "viewer",
-    "https://my-panoramax-server.net/api",
-    {
-	  style,
-      map: { startWide: true }
-    }
-  );
-});
-```
-
-## Adding aerial imagery
-
-In complement of classic _streets_ rendering, you can add an aerial imagery as map background. This is possible using a WMS or WMTS service, and setting configuration as following (this example uses the French IGN aerial imagery):
-
-```js
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		map: {
-			startWide: true,
-			raster: {
-				type: "raster",
-				tiles: [
-					"https://data.geopf.fr/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=ORTHOIMAGERY.ORTHOPHOTOS&STYLE=normal&FORMAT=image/jpeg&TILEMATRIXSET=PM_0_21&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}"
-				],
-				minzoom: 0,
-				maxzoom: 21,
-				attribution: "© IGN",
-				tileSize: 256
-			}
-		}
-	}
-);
-```
-
-## Use another geocoder
-
-The map offers a search bar for easily locating places based on user text search. This is handled by [MapLibre GL Geocoder](https://github.com/maplibre/maplibre-gl-geocoder). By default, the viewer uses [Nominatim](https://nominatim.org/) API, which provides geocoding using OpenStreetMap data.
-
-You can switch to using another geocoder though, we also directly offer the [Base adresse nationale](https://adresse.data.gouv.fr/) API (French authority geocoder) that you can use like this:
-
-```js
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		map: {
-			geocoder: { engine: "ban" }
-		}
-	}
-);
-```
-
-And you can also define your own custom geocoder using these options:
-
-```js
-var myOwnGeocoder = function(config) {
-	// Call your API
-	// Config parameter is based on geocoderApi.forwardGeocode.config structure
-	// Described here : https://github.com/maplibre/maplibre-gl-geocoder/blob/main/API.md#setgeocoderapi
-
-	// It returns a promise resolving on a Carmen GeoJSON FeatureCollection
-	// Format is described here : https://docs.mapbox.com/api/search/geocoding/#geocoding-response-object
-}
-
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		map: {
-			geocoder: { geocoderApi: {
-				forwardGeocode: myOwnGeocoder
-			} }
-		}
-	}
-);
-```
-
-## Authentication against API
-
-If the STAC API you're using needs some kind of authentication, you can pass it through Web Viewer options. Parameter `fetchOptions` allows you to set custom parameters for the [JS fetch function](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters), like the `credentials` setting. For example:
-
-```js
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://your-secured-stac.fr/api",
-	{
-		fetchOptions: {
-			credentials: "include"
-		}
-	}
-);
-```
-
-## Add custom buttons
-
-The viewer allows you to add a custom widget, placed just over the _Share_ button (bottom-right corner). It can be defined through `widgets.customWidget` option. Here's an example to add a simple link:
-
-```js
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		widgets: {
-			customWidget: `<a
-				href="https://my-amazing-page.net/"
-				class="gvs-btn gvs-widget-bg gvs-btn-large"
-				title="Go to an amazing page">🤩</a>`
-		},
-	}
-);
-```
-
-You can also pass more complex DOM elements:
-
-```js
-var myWidget = document.createElement("div");
-myWidget.innerHTML = "...";
-
-var viewer = new Panoramax.Viewer(
-	"viewer",
-	"https://my-panoramax-server.net/api",
-	{
-		widgets: { customWidget: myWidget }
-	}
-);
-```
-
-
-## Coverage map synced with external component
-
-Let's say you want to list all sequences of an user. You can display a standalone map which can be synced with your custom list.
-
-```js
-var map = new Panoramax.StandaloneMap(
-	"map",
-	"https://panoramax.ign.fr/api",
-	{
-		// Optional, to allow filtering by user
-		users: ["79b851b4-232a-4c96-ac1b-b6cf693c77ae"]
-	}
-);
-
-// Change visible map area
-map.fitBounds([west, south, east, north]);
-
-// Listen to user clicks on map
-map.addEventListener("select", e => {
-	console.log("Selected sequence", e.detail.seqId, "picture", e.detail.picId);
-});
-
-// Listen to sequence hovered on map
-map.addEventListener("hover", e => {
-	console.log("Hovered sequence", e.detail.seqId);
-});
-
-// You can also programatically change selection on map
-map.select(
-	"c463d190-06b0-47fb-98a8-b4a775a39ad6", // A sequence ID
-	"bdea1eb4-4496-46da-a4d5-b22b16e75fa8"  // A picture ID (can be null if unknown)
-);
-```
-
-
-## Clean-up in Single Page Application
-
-If you're running the viewer in a Single Page Application (SPA) and want to get rid of it, you must destroy properly the component before changing view. This allows the viewer to properly remove all its event listeners and free memory.
-
-```js
-viewer.destroy();
-delete viewer;
-```

package/src/Editor.css

@@ -1,37 +0,0 @@
-/* General layout */
-.gvs-editor {
-	display: flex;
-	flex-direction: column;
-}
-
-.gvs-editor .gvs-map,
-.gvs-editor .gvs-psv {
-	height: 50%;
-}
-
-/* Map background widget */
-.gvs-editor #gvs-map-bg {
-	display: flex;
-	gap: 20px;
-	justify-content: space-evenly;
-	margin: 10px;
-	padding: 7px;
-	width: unset;
-	border-radius: 10px;
-	position: absolute;
-	bottom: 0;
-}
-.gvs-editor #gvs-map-bg input { display: none; }
-.gvs-editor #gvs-map-bg label { cursor: pointer; }
-
-.gvs-editor #gvs-map-bg img {
-	width: 32px;
-	border-radius: 5px;
-	vertical-align: middle;
-	margin-right: 5px;
-	border: 2px solid var(--widget-bg);
-}
-
-.gvs-editor #gvs-map-bg input:checked + label img {
-	outline: 3px solid var(--widget-border-btn);
-}

package/src/Editor.js

@@ -1,361 +0,0 @@
-import "./Editor.css";
-import CoreView from "./components/CoreView";
-import Map from "./components/Map";
-import Photo from "./components/Photo";
-import BackgroundAerial from "./img/bg_aerial.jpg";
-import BackgroundStreets from "./img/bg_streets.jpg";
-import { linkMapAndPhoto, apiFeatureToPSVNode } from "./utils/Utils";
-import { VECTOR_STYLES } from "./utils/Map";
-import { SYSTEM as PSSystem } from "@photo-sphere-viewer/core";
-
-const LAYER_HEADING_ID = "sequence-headings";
-
-/**
- * Editor allows to focus on a single sequence, and preview what you edits would look like.
- * It shows both picture and map.
- * 
- * Note that you can use any of the [CoreView](#CoreView) class functions as well.
- * 
- * @param {string|Element} container The DOM element to create viewer into
- * @param {string} endpoint URL to API to use (must be a [STAC API](https://github.com/radiantearth/stac-api-spec/blob/main/overview.md))
- * @param {object} [options] View options.
- * @param {string} options.selectedSequence The ID of sequence to highlight on load. Must be always defined.
- * @param {string} [options.selectedPicture] The ID of picture to highlight on load (defaults to none)
- * @param {object} [options.fetchOptions=null] Set custom options for fetch calls made against API ([same syntax as fetch options parameter](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters))
- * @param {object} [options.raster] The MapLibre raster source for aerial background. This must be a JSON object following [MapLibre raster source definition](https://maplibre.org/maplibre-style-spec/sources/#raster).
- * @param {string} [options.background] Choose default map background to display (streets or aerial, if raster aerial background available). Defaults to street.
- * @param {string|object} [options.style] The map's MapLibre style. This can be an a JSON object conforming to the schema described in the [MapLibre Style Specification](https://maplibre.org/maplibre-gl-js-docs/style-spec/), or a URL string pointing to one.
- * 
- * @property {Map} map The map widget
- * @property {Photo} psv The photo widget
- */
-export default class Editor extends CoreView {
-	constructor(container, endpoint, options = {}){
-		super(container, endpoint, Object.assign(options, { users: [] }));
-
-		// Check sequence ID is set
-		if(!this._selectedSeqId) { this._loader.dismiss({}, "No sequence is selected"); }
-
-		// Create sub-containers
-		this.psvContainer = document.createElement("div");
-		this.mapContainer = document.createElement("div");
-		this.container.appendChild(this.psvContainer);
-		this.container.appendChild(this.mapContainer);
-
-		// Init PSV
-		try {
-			this.psv = new Photo(this, this.psvContainer);
-			this.psv._myVTour.datasource.nodeResolver = this._getNode.bind(this);
-		}
-		catch(e) {
-			let err = !PSSystem.isWebGLSupported ? this._t.gvs.error_webgl : this._t.gvs.error_psv;
-			this._loader.dismiss(e, err);
-		}
-
-		// Init map
-		this._api.onceReady().then(() => {
-			try {
-				this.map = new Map(this, this.mapContainer, {
-					raster: options.raster,
-					background: options.background,
-					supplementaryStyle: this._createMapStyle(),
-					zoom: 15, // Hack to avoid _initMapPosition call
-				});
-				linkMapAndPhoto(this);
-				this._loadSequence();
-				this.map.once("load", () => {
-					if(options.raster) { this._addMapBackgroundWidget(); }
-					this._bindPicturesEvents();
-				});
-
-				// Override picMarker setRotation for heading preview
-				const oldRot = this.map._picMarker.setRotation.bind(this.map._picMarker);
-				this.map._picMarker.setRotation = h => {
-					h = this._lastRelHeading === undefined ? h : h + this._lastRelHeading - this.psv.getPictureRelativeHeading();
-					return oldRot(h);
-				};
-			}
-			catch(e) {
-				this._loader.dismiss(e, this._t.gvs.error_psv);
-			}
-		});
-
-		// Events
-		this.addEventListener("select", this._onSelect.bind(this));
-	}
-
-	getClassName() {
-		return "Editor";
-	}
-
-	/**
-	 * Create style for GeoJSON sequence data.
-	 * @private
-	 */
-	_createMapStyle() {
-		return {
-			sources: {
-				geovisio_editor_sequences: {
-					type: "geojson",
-					data: {"type": "FeatureCollection", "features": [] }
-				}
-			},
-			layers: [
-				{
-					"id": "geovisio_editor_sequences",
-					"type": "line",
-					"source": "geovisio_editor_sequences",
-					"layout": {
-						...VECTOR_STYLES.SEQUENCES.layout
-					},
-					"paint": {
-						...VECTOR_STYLES.SEQUENCES.paint
-					},
-				},
-				{
-					"id": "geovisio_editor_pictures",
-					"type": "circle",
-					"source": "geovisio_editor_sequences",
-					"layout": {
-						...VECTOR_STYLES.PICTURES.layout
-					},
-					"paint": {
-						...VECTOR_STYLES.PICTURES.paint
-					},
-				}
-			]
-		};
-	}
-
-	/**
-	 * Creates events handlers on pictures layer
-	 * @private
-	 */
-	_bindPicturesEvents() {
-		// Pictures events
-		this.map.on("mousemove", "geovisio_editor_pictures", () => {
-			this.map.getCanvas().style.cursor = "pointer";
-		});
-
-		this.map.on("mouseleave", "geovisio_editor_pictures", () => {
-			this.map.getCanvas().style.cursor = "";
-		});
-
-		this.map.on("click", "geovisio_editor_pictures", this.map._onPictureClick.bind(this.map));
-	}
-
-	/**
-	 * Displays currently selected sequence on map
-	 * @private
-	 */
-	_loadSequence() {
-		return this._api.getSequenceItems(this._selectedSeqId).then(seq => {
-			// Hide loader after source load
-			this.map.once("sourcedata", () => {
-				this.map.setPaintProperty("geovisio_editor_sequences", "line-color", this.map._getLayerColorStyle("sequences"));
-				this.map.setPaintProperty("geovisio_editor_pictures", "circle-color", this.map._getLayerColorStyle("pictures"));
-				this.map.setLayoutProperty("geovisio_editor_sequences", "visibility", "visible");
-				this.map.setLayoutProperty("geovisio_editor_pictures", "visibility", "visible");
-				this.map.once("styledata", () => this._loader.dismiss());
-			});
-
-			// Create data source
-			this._sequenceData = seq.features;
-			this.map.getSource("geovisio_editor_sequences").setData({
-				"type": "FeatureCollection",
-				"features": [
-					{
-						"type": "Feature",
-						"properties": {
-							"id": this._selectedSeqId,
-						},
-						"geometry":
-						{
-							"type": "LineString",
-							"coordinates": seq.features.map(p => p.geometry.coordinates)
-						}
-					},
-					...seq.features.map(f => {
-						f.properties.id = f.id;
-						f.properties.sequences = [this._selectedSeqId];
-						return f;
-					})
-				]
-			});
-
-			// Select picture if any
-			if(this._selectedPicId) {
-				const pic = seq.features.find(p => p.id === this._selectedPicId);
-				if(pic) {
-					this.select(this._selectedSeqId, this._selectedPicId, true);
-					this.map.jumpTo({ center: pic.geometry.coordinates, zoom: 18 });
-				}
-				else {
-					console.log("Picture with ID", pic, "was not found");
-				}
-			}
-			// Show area of sequence otherwise
-			else {
-				const bbox = [
-					...seq.features[0].geometry.coordinates,
-					...seq.features[0].geometry.coordinates
-				];
-
-				for(let i=1; i < seq.features.length; i++) {
-					const c = seq.features[i].geometry.coordinates;
-					if(c[0] < bbox[0]) { bbox[0] = c[0]; }
-					if(c[1] < bbox[1]) { bbox[1] = c[1]; }
-					if(c[0] > bbox[2]) { bbox[2] = c[0]; }
-					if(c[1] > bbox[3]) { bbox[3] = c[1]; }
-				}
-
-				this.map.fitBounds(bbox, {animate: false});
-			}
-		}).catch(e => this._loader.dismiss(e, this._t.gvs.error_api));
-	}
-
-	/**
-	 * Get the PSV node for wanted picture.
-	 * 
-	 * @param {string} picId The picture ID
-	 * @returns The PSV node
-	 * @private
-	 */
-	_getNode(picId) {
-		const f = this._sequenceData.find(f => f.properties.id === picId);
-		const n = f ? apiFeatureToPSVNode(f, this._t, this._isInternetFast) : null;
-		if(n) { delete n.links; }
-		return n;
-	}
-
-	/**
-	 * Creates the widget to switch between aerial and streets imagery
-	 * @private
-	 */
-	_addMapBackgroundWidget() {
-		// Container
-		const pnlLayers = document.createElement("div");
-		pnlLayers.id = "gvs-map-bg";
-		pnlLayers.classList.add("gvs-panel", "gvs-widget-bg", "gvs-input-group");
-		const onBgChange = e => this.map.setBackground(e.target.value);
-
-		// Radio streets
-		const radioBgStreets = document.createElement("input");
-		radioBgStreets.id = "gvs-map-bg-streets";
-		radioBgStreets.setAttribute("type", "radio");
-		radioBgStreets.setAttribute("name", "gvs-map-bg");
-		radioBgStreets.setAttribute("value", "streets");
-		radioBgStreets.addEventListener("change", onBgChange);
-		pnlLayers.appendChild(radioBgStreets);
-
-		const labelBgStreets = document.createElement("label");
-		labelBgStreets.setAttribute("for", radioBgStreets.id);
-
-		const imgBgStreets = document.createElement("img");
-		imgBgStreets.src = BackgroundStreets;
-		imgBgStreets.alt = "";
-
-		labelBgStreets.appendChild(imgBgStreets);
-		labelBgStreets.appendChild(document.createTextNode(this._t.gvs.map_background_streets));
-		pnlLayers.appendChild(labelBgStreets);
-		
-		// Radio aerial
-		const radioBgAerial = document.createElement("input");
-		radioBgAerial.id = "gvs-map-bg-aerial";
-		radioBgAerial.setAttribute("type", "radio");
-		radioBgAerial.setAttribute("name", "gvs-map-bg");
-		radioBgAerial.setAttribute("value", "aerial");
-		radioBgAerial.addEventListener("change", onBgChange);
-		pnlLayers.appendChild(radioBgAerial);
-
-		const labelBgAerial = document.createElement("label");
-		labelBgAerial.setAttribute("for", radioBgAerial.id);
-
-		const imgBgAerial = document.createElement("img");
-		imgBgAerial.src = BackgroundAerial;
-		imgBgAerial.alt = "";
-
-		labelBgAerial.appendChild(imgBgAerial);
-		labelBgAerial.appendChild(document.createTextNode(this._t.gvs.map_background_aerial));
-		pnlLayers.appendChild(labelBgAerial);
-
-		this.mapContainer.appendChild(pnlLayers);
-
-		const onMapBgChange = bg => {
-			if(bg === "aerial") { radioBgAerial.checked = true; }
-			else { radioBgStreets.checked = true; }
-		};
-		this.addEventListener("map:background-changed", e => onMapBgChange(e.detail.background));
-		onMapBgChange(this.map.getBackground());
-	}
-
-	/**
-	 * Preview on map how the new relative heading would reflect on all pictures.
-	 * This doesn't change anything on API-side, it's just a preview.
-	 * 
-	 * @param {number} [relHeading] The new relative heading compared to sequence path. In degrees, between -180 and 180 (0 = front, -90 = left, 90 = right). Set to null to remove preview.
-	 */
-	previewSequenceHeadingChange(relHeading) {
-		const layerExists = this.map.getLayer(LAYER_HEADING_ID) !== undefined;
-		this.map._picMarkerPreview.remove();
-
-		// If no value set, remove layer
-		if(relHeading === undefined) {
-			delete this._lastRelHeading;
-			if(layerExists) {
-				this.map.setLayoutProperty(LAYER_HEADING_ID, "visibility", "none");
-			}
-			// Update selected picture marker
-			if(this._selectedPicId) {
-				this.map._picMarker.setRotation(this.psv.getXY().x);
-			}
-			return;
-		}
-
-		this._lastRelHeading = relHeading;
-
-		// Create preview layer
-		if(!layerExists) {
-			this.map.addLayer({
-				"id": LAYER_HEADING_ID,
-				"type": "symbol",
-				"source": "geovisio_editor_sequences",
-				"layout": {
-					"icon-image": "gvs-marker",
-					"icon-overlap": "always",
-					"icon-size": 0.8,
-				},
-			});
-		}
-
-		// Change heading
-		const currentRelHeading = - this.psv.getPictureRelativeHeading();
-		this.map.setLayoutProperty(LAYER_HEADING_ID, "visibility", "visible");
-		this.map.setLayoutProperty(
-			LAYER_HEADING_ID,
-			"icon-rotate",
-			["+", ["get", "view:azimuth"], currentRelHeading, relHeading ]
-		);
-
-		// Skip selected picture and linestring geom
-		const filters = [["==", ["geometry-type"], "Point"]];
-		if(this._selectedPicId) { filters.push(["!=", ["get", "id"], this._selectedPicId]); }
-		this.map.setFilter(LAYER_HEADING_ID, ["all", ...filters]);
-
-		// Update selected picture marker
-		if(this._selectedPicId) {
-			this.map._picMarker.setRotation(this.psv.getXY().x);
-		}
-	}
-
-	/**
-	 * Event handler for picture loading
-	 * @private
-	 */
-	_onSelect() {
-		// Update preview of heading change
-		if(this._lastRelHeading !== undefined) {
-			this.previewSequenceHeadingChange(this._lastRelHeading);
-		}
-	}
-}