@panoramax/web-viewer 3.2.3-develop-d7e5a16d → 3.2.3-develop-f9c0224b

package/src/utils/API.js

@@ -1,17 +1,18 @@
-import { TILES_PICTURES_ZOOM } from "./Map";
-import { BASE_PANORAMA_ID } from "./Utils";
+import { TILES_PICTURES_ZOOM } from "./map";
+import { BASE_PANORAMA_ID } from "./utils";
 
 /**
- * API contains various utility functions to communicate with the backend
+ * API contains various utility functions to communicate with Panoramax/STAC API
  *
- * @param {string} endpoint The API endpoint. It corresponds to the <a href="https://github.com/radiantearth/stac-api-spec/blob/main/overview.md#example-landing-page">STAC landing page</a>, with all links describing the API capabilites.
- * @param {object} [options] Options received from viewer that may change API behaviour
+ * @class Panoramax.utils.API
+ * @typicalname api
+ * @param {string} endpoint The endpoint. It corresponds to the <a href="https://github.com/radiantearth/stac-api-spec/blob/main/overview.md#example-landing-page">STAC landing page</a>, with all links describing the API capabilites.
+ * @param {object} [options] Options
  * @param {string|object} [options.style] General map style
  * @param {string} [options.tiles] API route serving pictures & sequences vector tiles
- * @param {boolean} [options.skipReadLanding] True to not call API landing page automatically (defaults to false)
+ * @param {boolean} [options.skipReadLanding=false] True to not call API landing page automatically
  * @param {object} [options.fetch] 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 {string[]} [options.users] List of initial user IDs to load map styles for.
- * @private
+ * @param {string[]} [options.users] List of initial user IDs to load map styles for
  */
 export default class API {
 	constructor(endpoint, options = {}) {
@@ -52,9 +53,11 @@ export default class API {
 	}
 
 	/**
-	 * This function resolves when API is ready to be used
-	 *
-	 * @returns {Promise} Resolves when API is ready
+	 * Resolves when the API is ready to be used.
+	 * @memberOf Panoramax.utils.API#
+	 * @returns {Promise}
+	 * @fulfil {string} "API is ready" when initialization is complete.
+	 * @reject {string} Error message
 	 */
 	onceReady() {
 		if(this._isReady == -1) {
@@ -69,9 +72,9 @@ export default class API {
 	}
 
 	/**
-	 * Check if API is ready to be used
-	 *
-	 * @returns {boolean} True if ready
+	 * Checks if the API is ready to be used.
+	 * @memberOf Panoramax.utils.API#
+	 * @returns {boolean} True if the API is ready, false otherwise.
 	 */
 	isReady() {
 		return this._isReady == 1;
@@ -79,6 +82,7 @@ export default class API {
 
 	/**
 	 * List of available features offered by API
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {string[]} Keywords of enabled features
 	 */
 	getAvailableFeatures() {
@@ -87,6 +91,7 @@ export default class API {
 
 	/**
 	 * List of unavailable features on API
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {string[]} Keywords of disabled features
 	 */
 	getUnavailableFeatures() {
@@ -95,7 +100,7 @@ export default class API {
 
 	/**
 	 * Interprets JSON landing page and store important information
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @private
 	 */
 	_parseLanding(landing, options) {
@@ -252,9 +257,12 @@ export default class API {
 
 	/**
 	 * Loads all MapLibre Styles JSON needed at start.
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string|object} style General map style
 	 * @param {string[]} users List of user IDs to handle. Should include special user "geovisio" for general tiles loading.
-	 * @returns {Promise} Resolves when style is ready.
+	 * @returns {Promise} 
+	 * @fulfil {null} When style is ready.
+	 * @private
 	 */
 	_loadMapStyles(style, users) {
 		const mapUsers = new Set(users || []);
@@ -298,7 +306,7 @@ export default class API {
 
 	/**
 	 * Get the defaults fetch options to pass during API calls
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @private
 	 * @returns {object} The fetch options
 	 */
@@ -310,7 +318,7 @@ export default class API {
 
 	/**
 	 * Get the RequestTransformFunction for MapLibre to handle fetch options
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @private
 	 * @returns {function} The RequestTransformFunction
 	 */
@@ -335,11 +343,13 @@ export default class API {
 
 	/**
 	 * Get sequence GeoJSON representation
-	 * 
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @param {string} [next] The next link URL (only for internals)
 	 * @param {object} [data] The previous dataset (only for internals)
-	 * @returns {Promise} Resolves on sequence GeoJSON
+	 * @returns {Promise}
+	 * @fulfil {object} Sequence GeoJSON
+	 * @reject {Error} If API is not ready or for any network issue
 	 */
 	async getSequenceItems(seqId, next = null, data = null) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -368,7 +378,7 @@ export default class API {
 
 	/**
 	 * Get full URL for listing pictures around a specific location
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {number} lat Latitude
 	 * @param {number} lon Longitude
 	 * @param {number} [factor] The radius to search around (in degrees)
@@ -391,13 +401,14 @@ export default class API {
 
 	/**
 	 * Get list of pictures around a specific location
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {number} lat Latitude
 	 * @param {number} lon Longitude
 	 * @param {number} [factor] The radius to search around (in degrees)
 	 * @param {number} [limit] Max amount of pictures to retrieve
 	 * @param {string} [seqId] The sequence ID to filter on (by default, no filter)
-	 * @returns {object} The GeoJSON feature collection
+	 * @returns {Promise}
+	 * @fulfil {object} The GeoJSON feature collection
 	 */
 	getPicturesAroundCoordinates(lat, lon, factor, limit, seqId) {
 		return fetch(this.getPicturesAroundCoordinatesUrl(lat, lon, factor, limit, seqId), this._getFetchOptions())
@@ -406,10 +417,11 @@ export default class API {
 
 	/**
 	 * Get full URL for retrieving a specific picture metadata
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} picId The picture unique identifier
 	 * @param {string} [seqId] The sequence ID
 	 * @returns {string} The corresponding URL
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureMetadataUrl(picId, seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -422,8 +434,10 @@ export default class API {
 
 	/**
 	 * Get JSON style for general vector tiles
-	 * @return {Promise} The MapLibre JSON style
-	 * @fires Error If API is not ready, or no style defined.
+	 * @memberOf Panoramax.utils.API#
+	 * @return {Promise|object} Promise if first load, MapLibre JSON style otherwise
+	 * @fulfil {object} The MapLibre JSON style
+	 * @reject {Error} If API is not ready, or no style defined.
 	 */
 	getMapStyle() {
 		if(this.isReady()) { return this.mapStyle; }
@@ -471,10 +485,12 @@ export default class API {
 
 	/**
 	 * Get JSON style for specific-user vector tiles
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} userId The user UUID
 	 * @param {boolean} [skipReadyCheck=false] Skip check for API readyness
-	 * @return {Promise} The MapLibre JSON style
-	 * @fires Error If API is not ready, or no style defined.
+	 * @return {Promise}
+	 * @fulfil {object} The MapLibre JSON style
+	 * @reject {Error} If API is not ready, or no style defined.
 	 */
 	getUserMapStyle(userId, skipReadyCheck = false) {
 		if(!skipReadyCheck && !this.isReady()) { return Promise.reject(new Error("API is not ready to use")); }
@@ -515,9 +531,10 @@ export default class API {
 
 	/**
 	 * Find the thumbnail URL for a given picture
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {object} picture The picture GeoJSON feature
 	 * @returns {string} The thumbnail URL, or null if not found
+	 * @throws {Error} If API is not ready
 	 * @private
 	 */
 	findThumbnailInPictureFeature(picture) {
@@ -538,10 +555,12 @@ export default class API {
 
 	/**
 	 * Get a picture thumbnail URL for a given sequence
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @param {object} [seq] The sequence metadata (with links) if already loaded
-	 * @returns {Promise} Promise resolving on the picture thumbnail URL, or null if not found
+	 * @returns {Promise}
+	 * @fulfil {string|null} Promise resolving on the picture thumbnail URL, or null if not found
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureThumbnailURLForSequence(seqId, seq) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -575,10 +594,12 @@ export default class API {
 
 	/**
 	 * Get thumbnail URL for a specific picture
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} picId The picture unique identifier
 	 * @param {string} [seqId] The sequence ID
-	 * @returns {Promise} The corresponding URL on resolve, or undefined if no thumbnail could be found
+	 * @returns {Promise}
+	 * @fulfil {string|null} The corresponding URL on resolve, or null if no thumbnail could be found
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureThumbnailURL(picId, seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -610,9 +631,10 @@ export default class API {
 
 	/**
 	 * Get the RSS feed URL with map parameters (if map is enabled)
-	 * 
+	 * @memberOf Panoramax.utils.API#
 	 * @param {LngLatBounds} [bbox] The map current bounding box, or null if not available
-	 * @returns {string} The URL, or null if no RSS feed is available
+	 * @returns {string|null} The URL, or null if no RSS feed is available
+	 * @throws {Error} If API is not ready
 	 */
 	getRSSURL(bbox) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -632,9 +654,10 @@ export default class API {
 
 	/**
 	 * Get full URL for retrieving a specific sequence metadata
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @returns {string} The corresponding URL
+	 * @throws {Error} If API is not ready
 	 */
 	getSequenceMetadataUrl(seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -643,8 +666,9 @@ export default class API {
 
 	/**
 	 * Get available data bounding box
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {LngLatBoundsLike} The bounding box or null if not available
+	 * @throws {Error} If API is not ready
 	 */
 	getDataBbox() {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -654,8 +678,11 @@ export default class API {
 
 	/**
 	 * Look for user ID based on user name query
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} query The user name to look for
-	 * @returns {Promise} Resolves on list of potential users
+	 * @returns {Promise}
+	 * @fulfil {object|null} List of potential users
+	 * @throws {Error} If API is not ready or user search not available
 	 */
 	searchUsers(query) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -670,8 +697,11 @@ export default class API {
 
 	/**
 	 * Get user name based on its ID
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} userId The user UUID
-	 * @returns {Promise} Resolves on user name
+	 * @returns {Promise}
+	 * @throws {Error} If API is not ready
+	 * @fulfil {string|null} The user name (or null if not found)
 	 */
 	getUserName(userId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -686,8 +716,10 @@ export default class API {
 
 	/**
 	 * Send a report to API
+	 * @memberOf Panoramax.utils.API#
 	 * @param {object} data The input form data
-	 * @returns {Promise} Resolves on report sent
+	 * @returns {Promise}
+	 * @fulfil {object} The JSON API response
 	 */
 	sendReport(data) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -715,7 +747,7 @@ export default class API {
 
 	/**
 	 * Checks URL string validity
-	 *
+	 * @memberOf Panoramax.utils.API
 	 * @param {string} str The URL to check
 	 * @returns {boolean} True if valid
 	 */
@@ -733,7 +765,7 @@ export default class API {
 
 	/**
 	 * Checks picture or sequence ID validity
-	 *
+	 * @memberOf Panoramax.utils.API
 	 * @param {string} id The ID to check
 	 * @returns {boolean} True if valid
 	 * @throws {Error} If not valid

package/src/utils/InitParameters.js

@@ -0,0 +1,354 @@
+export const MAP_FILTERS_JS2URL = {
+	"minDate": "date_from",
+	"maxDate": "date_to",
+	"pic_type": "pic_type",
+	"camera": "camera",
+	"theme": "theme",
+	"qualityscore": "pic_score",
+};
+
+const MAP_FILTERS_URL2JS = Object.fromEntries(Object.entries(MAP_FILTERS_JS2URL).map(v => [v[1], v[0]]));
+const MAP_NONE = ["none", "null", "false", false];
+
+/**
+ * Merges all URL parameters and component attributes into a single set of coherent settings.
+ * 
+ * @class Panoramax.utils.InitParameters
+ * @param {object} [componentAttrs] HTML attributes from parent component
+ * @param {object} [urlParams] Parameters extracted from URL
+ */
+export default class InitParameters { // eslint-disable-line import/no-unused-modules
+	constructor(componentAttrs = {}, urlParams = {}) {
+		// Skip URL parameters if disabled by component
+		if(componentAttrs["url-parameters"] === "false") { urlParams = {}; }
+
+		// Sanitize PSV parameters
+		let componentPsv = {};
+		if(typeof componentAttrs?.psv === "object") { componentPsv = componentAttrs.psv; }
+
+		// Sanitize Map parameters
+		let componentMap = {};
+		if(typeof componentAttrs?.map === "object") { componentMap = componentAttrs.map; }
+
+		// Extract map position from URL
+		let urlMap = urlParams.map && urlParams.map !== "none" ? getMapPositionFromString(urlParams.map) : null;
+
+		// Parse and prioritize all parameters
+		//  - Overlapping between URL & component
+		let map = MAP_NONE.includes(urlParams.map) || MAP_NONE.includes(componentAttrs.map) ? false : true;
+		let focus = urlParams.focus || componentAttrs.focus;
+		let picture = urlParams.pic || componentAttrs.picture;
+		let users = urlParams.users || componentAttrs.users;
+		let psv_speed = urlParams.speed || componentPsv?.transitionDuration;
+		let psv_nav = urlParams.nav || componentPsv?.picturesNavigation;
+		let map_theme = urlParams.theme || componentMap.theme;
+		let map_background = urlParams.background || componentMap.background;
+		let map_center = urlMap?.center || componentMap.center;
+		let map_zoom = urlMap?.zoom || componentMap.zoom;
+		let map_pitch = urlMap?.pitch || componentMap.pitch;
+		let map_bearing = urlMap?.bearing || componentMap.bearing;
+		
+		//  - Component only
+		let geocoder = componentAttrs.geocoder;
+		let widgets = componentAttrs.widgets;
+		let sequence = componentAttrs.sequence;
+		let fetchOptions = componentAttrs.fetchOptions;
+		let style = componentAttrs.style;
+		let lang = componentAttrs.lang;
+		let endpoint = componentAttrs.endpoint;
+		let map_raster = componentMap.raster;
+
+		//  - URL only
+		let psv_xyz = urlParams.xyz;
+		let map_date_from = urlParams.date_from;
+		let map_date_to = urlParams.date_to;
+		let map_pic_type = urlParams.pic_type;
+		let map_camera = urlParams.camera;
+		let map_pic_score = urlParams.pic_score;
+
+		// Check coherence
+		if(!["map", "meta", "pic"].includes(focus)) {
+			console.warn("Invalid value for parameter focus:", focus);
+			focus = map && !picture ? "map" : "pic";
+		}
+		else if(focus === "map" && !map) {
+			console.warn("Parameter focus can't be 'map' as map is disabled");
+			focus = "pic";
+		}
+		if(map_background == "aerial" && !map_raster) {
+			console.warn("Parameter background can't be 'aerial' as no aerial imagery is available");
+			map_background = "streets";
+		}
+		if(map && !picture) {
+			focus = "map";
+		}
+
+		// Put all attributes in appropriate container
+		this._parentInit = { map, users, fetchOptions, style, lang, endpoint };
+		this._parentPostInit = { focus, picture, sequence, geocoder, widgets, forceFocus: true };
+
+		this._psvInit = Object.fromEntries(
+			Object.entries(componentPsv).filter(
+				([k,]) => !["transitionDuration", "picturesNavigation"].includes(k)
+			)
+		);
+		this._psvAny = {
+			transitionDuration: psv_speed,
+			picturesNavigation: psv_nav,
+		};
+		this._psvPostInit = { xyz: psv_xyz };
+
+		this._mapInit = { raster: map_raster };
+		this._mapAny = {
+			theme: map_theme,
+			background: map_background,
+			center: map_center,
+			zoom: map_zoom,
+			pitch: map_pitch,
+			bearing: map_bearing,
+			users,
+		};
+		this._mapPostInit = {
+			date_from: map_date_from,
+			date_to: map_date_to,
+			pic_type: map_pic_type,
+			camera: map_camera,
+			pic_score: map_pic_score,
+		};
+	}
+
+	/**
+	 * Cleans out undefined values from object.
+	 * @param {object} obj The input object
+	 * @returns {object} Clean object without undefined values
+	 * @private
+	 */
+	_sanitize(obj) {
+		return Object.fromEntries(Object.entries(obj).filter(([,v]) => v !== undefined));
+	}
+
+	/**
+	 * Get core component initialization parameters.
+	 * They must be passed as soon as possible.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getParentInit() {
+		return this._sanitize(this._parentInit);
+	}
+
+	/**
+	 * Get core component post-initialization parameters.
+	 * They must be passed after first rendering or init.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getParentPostInit() {
+		return this._sanitize(this._parentPostInit);
+	}
+
+	/**
+	 * Get Photo Sphere Viewer initialization parameters.
+	 * They must be passed as soon as possible.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getPSVInit() {
+		return this._sanitize(Object.assign({}, this._psvInit, this._psvAny));
+	}
+
+	/**
+	 * Get Photo Sphere Viewer post-initialization parameters.
+	 * They must be passed after first rendering or init.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getPSVPostInit() {
+		return this._sanitize(Object.assign({}, this._psvPostInit, this._psvAny));
+	}
+
+	/**
+	 * Get MapLibre GL initialization parameters.
+	 * They must be passed as soon as possible.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getMapInit() {
+		return this._sanitize(Object.assign({}, this._mapInit, this._mapAny));
+	}
+
+	/**
+	 * Get MapLibre GL post-initialization parameters.
+	 * They must be passed after first rendering or init.
+	 * @memberof Panoramax.utils.InitParameters#
+	 */
+	getMapPostInit() {
+		return this._sanitize(Object.assign({}, this._mapPostInit, this._mapAny));
+	}
+
+	/**
+	 * Reads public properties from LitElement and returns a classic key-value object.
+	 * @param {class} compClass The component class (with static `properties` definition)
+	 * @param {LitElement} comp The component itself
+	 */
+	static GetComponentProperties(compClass, comp) {
+		const props = {};
+		for(let classK in compClass.properties) {
+			let classV = compClass.properties[classK];
+			if(!classV.state && comp[classK] != null) {
+				props[classK] = comp[classK];
+			}
+		}
+		return props;
+	}
+}
+
+/**
+ * Extracts map center, zoom & more from formatted string.
+ * @param {string} str The map position as hash string
+ * @param {Panoramax.components.ui.Map} [map] The current map
+ * @returns {object} { center, zoom, pitch, bearing }
+ * @private
+ */
+export function getMapPositionFromString(str, map) {
+	const loc = (str || "").split("/");
+	if (loc.length >= 3 && !loc.some(v => isNaN(v))) {
+		const res = {
+			center: [+loc[2], +loc[1]],
+			zoom: +loc[0],
+			pitch: +(loc[4] || 0)
+		};
+
+		if(map) {
+			res.bearing = map.dragRotate.isEnabled() && map.touchZoomRotate.isEnabled() ? +(loc[3] || 0) : map.getBearing();
+		}
+
+		return res;
+	}
+	else { return null; }
+}
+
+/**
+ * Extracts from string xyz position
+ * @param {string} str The xyz position as hash string
+ * @returns {object} { x, y, z }
+ * @private
+ */
+export function xyzParamToPSVPosition(str) {
+	const loc = (str || "").split("/");
+	if (loc.length === 3 && !loc.some(v => isNaN(v))) {
+		const res = {
+			x: +loc[0],
+			y: +loc[1],
+			z: +loc[2]
+		};
+
+		return res;
+	}
+	else { return null; }
+}
+
+/**
+ * Extracts from hash parsed keys all map filters values
+ * @param {*} vals Hash keys
+ * @returns {object} Map filters
+ * @private
+ */
+export function paramsToMapFilters(vals) {
+	const newMapFilters = {};
+	for(let k in MAP_FILTERS_URL2JS) {
+		if(vals[k]) {
+			newMapFilters[MAP_FILTERS_URL2JS[k]] = vals[k];
+		}
+	}
+	if(newMapFilters.qualityscore) {
+		let values = newMapFilters.qualityscore.split("");
+		const mapping = {"A": 5, "B": 4, "C": 3, "D": 2, "E": 1};
+		newMapFilters.qualityscore = values.map(v => mapping[v]);
+	}
+	return newMapFilters;
+}
+
+/**
+ * Change PSV current state based on standardized parameters.
+ * @param {Photo} psv The Photo Sphere Viewer component to change.
+ * @param {object} params The parameters to apply.
+ */
+export function alterPSVState(psv, params) {
+	// Change xyz position
+	if(params.xyz) {
+		psv.addEventListener("picture-loaded", () => {
+			const coords = xyzParamToPSVPosition(params.xyz);
+			psv.setXYZ(coords.x, coords.y, coords.z);
+		}, {once: true});
+	}
+
+	// Change transitionDuration
+	if(params.transitionDuration !== undefined) {
+		psv.setTransitionDuration(params.transitionDuration);
+	}
+
+	// Change pictures navigation mode
+	if(["pic", "any", "seq"].includes(params.picturesNavigation)) {
+		psv.setPicturesNavigation(params.picturesNavigation);
+	}
+}
+
+/**
+ * Change MapLibre GL current state based on standardized parameters.
+ * @param {Map} map The MapLibre component to change.
+ * @param {object} params The parameters to apply.
+ */
+export function alterMapState(map, params) {
+	// Map position
+	const mapOpts = getMapPositionFromString(params.map, map);
+	if(mapOpts) {
+		map.jumpTo(mapOpts);
+	}
+
+	// Visible users
+	let vu = Array.isArray(params.users) ? params.users : (params.users || "").split(",");
+	if(vu.length === 0 || (vu.length === 1 && vu[0].trim() === "")) { vu = ["geovisio"]; }
+	map.setVisibleUsers(vu);
+
+	// Change map filters
+	map.setFilters(paramsToMapFilters(params));
+
+	// Change map background
+	if(["aerial", "streets"].includes(params.background)) {
+		map.setBackground(params.background);
+	}
+}
+
+/**
+ * Change Viewer current state based on standardized parameters.
+ * @param {Viewer} viewer The Viewer component to change.
+ * @param {object} params The parameters to apply.
+ */
+export function alterViewerState(viewer, params) {
+	// Restore selected picture
+	if(params.picture) {
+		const picIds = params.picture.split(";"); // Handle multiple IDs coming from OSM
+		if(picIds.length > 1) {
+			console.warn("Multiple picture IDs passed in URL, only first one kept");
+		}
+
+		// Post-load changes
+		if(params.focus && params.focus == "meta") {
+			viewer.psv.addEventListener("picture-loaded", () => viewer._showPictureMetadata(), { once: true });
+		}
+
+		viewer.select(null, picIds[0]);
+	}
+	else {
+		viewer.select();
+	}
+
+	// Change focus
+	if(params.focus === "map" && viewer?.map) {
+		viewer.setPopup(false);
+		viewer._setFocus("map", null, params.forceFocus);
+	}
+	else if(params.focus === "pic") {
+		viewer.setPopup(false);
+		viewer._setFocus("pic", null, params.forceFocus);
+	}
+	else if(params.focus && params.focus === "meta") {
+		viewer._setFocus("pic", null, params.forceFocus);
+	}
+}