Viewer's API reference
Table of Contents
CoreView
Extends EventTarget
Core view is an abstract class used for setting up any of the main Panoramax JS view components.
It is used to prepare API, internationalization, options checks... for Viewer, StandaloneMap and Editor classes.
Parameters
container
(string | Element) The DOM element to create viewer intoendpoint
string URL to API to use (must be a STAC API)-
options
object? View options. (optional, default{}
)options.selectedSequence
string? The ID of sequence to highlight on load (defaults to none)options.selectedPicture
string? The ID of picture to highlight on load (defaults to none)options.fetchOptions
object Set custom options for fetch calls made against API (same syntax as fetch options parameter) (optional, defaultnull
)options.users
(string | Array<string>)? List of user IDs to default use for display. Defaults to all users.options.style
(string | object)? The map's MapLibre style. This can be an a JSON object conforming to the schema described in the MapLibre Style Specification, or a URL string pointing to one. Defaults to OSMFR vector tiles.
Properties
_t
object The translations labels_selectedSeqId
string The selected sequence ID_selectedPicId
string The selected picture ID_api
API The API handler_loader
Loader The initial loader message_options
object The stored optionscontainer
Element The DOM container
getClassName
This allows to retrieve an always correct class name. This is crap, but avoids issues with Webpack & so on.
Each inheriting class must override this method.
destroy
Ends all form of life in this object.
This is useful for Single Page Applications (SPA), to remove various event listeners.
isWidthSmall
Is the view running in a small container (small embed or smartphone)
Returns boolean True if container is small
isHeightSmall
Is the view running in a small-height container (small embed or smartphone)
Returns boolean True if container height is small
select
Change the currently picture and/or sequence. Calling the method without parameters unselects.
Parameters
seqId
string? The sequence UUID (optional, defaultnull
)picId
string? The picture UUID (optional, defaultnull
)force
boolean Force select even if already selected (optional, defaultfalse
)
select
Event for sequence/picture selection
Type: object
Properties
-
detail
object Event information
ready
Event for viewer being ready to use (API loaded)
broken
Event for viewer failing to initially load
Type: object
Properties
map:background-changed
Event for map background changes
Type: object
Properties
-
detail
object Event informationdetail.background
string? The new selected background (aerial, streets)
map:users-changed
Event for visible users changes
Type: object
Properties
map:sequence-hover
Event when a sequence on map is hovered (not selected)
Type: object
Properties
map:sequence-click
Event when a sequence on map is clicked
Type: object
Properties
-
detail
object Event informationdetail.seqId
string The clicked sequence IDdetail.coordinates
maplibregl.LngLat The coordinates of user click
map:picture-click
Event when a picture on map is clicked
Type: object
Properties
-
detail
object Event information
psv:picture-loading
Event for picture starting to load
Type: object
Properties
-
detail
object Event informationdetail.picId
string The picture unique identifierdetail.lon
number Longitude (WGS84)detail.lat
number Latitude (WGS84)detail.x
number New x position (in degrees, 0-360), corresponds to heading (0° = North, 90° = East, 180° = South, 270° = West)detail.y
number New y position (in degrees)detail.z
number New z position (0-100)
psv:picture-preview-started
Event for picture preview
Type: object
Properties
-
detail
object Event information
psv:picture-preview-stopped
Event for end of picture preview
Type: object
Properties
psv:view-rotated
Event for viewer rotation
Type: object
Properties
-
detail
object Event information
psv:picture-loaded
Event for picture load (low-resolution image is loaded)
Type: object
Properties
-
detail
object Event informationdetail.picId
string The picture unique identifierdetail.lon
number Longitude (WGS84)detail.lat
number Latitude (WGS84)detail.x
number New x position (in degrees, 0-360), corresponds to heading (0° = North, 90° = East, 180° = South, 270° = West)detail.y
number New y position (in degrees)detail.z
number New z position (0-100)
psv:picture-tiles-loaded
Event launched when all visible tiles of a picture are loaded
Type: object
Properties
psv:transition-duration-changed
Event for transition duration change
Type: object
Properties
Map
Extends maplibregl.Map
Map is the component showing pictures and sequences geolocation.
Note that all functions of MapLibre GL JS class Map are also available.
Parameters
parent
CoreView The parent viewcontainer
Element The DOM element to create into-
options
object? The map options (any of MapLibre GL settings or any supplementary option defined here) (optional, default{}
)options.raster
object? The MapLibre raster source for aerial background. This must be a JSON object following MapLibre raster source definition.options.background
string? Choose default map background to display (streets or aerial, if raster aerial background available). Defaults to street.-
options.geocoder
object? Optional geocoder settingsoptions.geocoder.engine
string? Set the geocoder engine to use (nominatim, ban)
destroy
Destroy any form of life in this component
reloadVectorTiles
Force refresh of vector tiles data
hasTwoBackgrounds
Check if map offers aerial imagery as well as streets rendering.
Returns boolean True if aerial imagery is available for display
getBackground
Get the currently selected map background
Returns string aerial or streets
setBackground
Change the shown background in map.
Parameters
bg
string The new background to display (aerial or streets)
getVisibleUsers
Get the currently visible users
Returns Array<string> List of visible users
setVisibleUsers
Make given user layers visible on map, and hide all others (if any)
Parameters
filterUserLayersContent
Filter the visible data content in all visible map layers
Parameters
displayPictureMarker
Shows on map a picture position and heading.
Parameters
reloadLayersStyles
Forces reload of pictures/sequences layer styles. This is useful after a map theme change.
Photo
Extends PSViewer
Photo is the component showing a single picture. It uses Photo Sphere Viewer as a basis, and pre-configure dialog with STAC API.
Note that all functions of PhotoSphereViewer Viewer class are available as well.
Parameters
parent
CoreView The parent viewcontainer
Element The DOM element to create into-
options
object? The viewer options. Can be any of Photo Sphere Viewer options (optional, default{}
)
getPictureMetadata
Access currently shown picture metadata
Returns object Picture metadata
goToNextPicture
Displays next picture in current sequence (if any)
goToPrevPicture
Displays previous picture in current sequence (if any)
goToPosition
Displays in viewer a picture near to given coordinates
Parameters
Returns Promise Resolves on picture ID if picture found, otherwise rejects
getXY
Get 2D position of sphere currently shown to user
Returns object Position in format { x: heading in degrees (0° = North, 90° = East, 180° = South, 270° = West), y: top/bottom position in degrees (-90° = bottom, 0° = front, 90° = top) }
getXYZ
Get 3D position of sphere currently shown to user
Returns object Position in format { x: heading in degrees (0° = North, 90° = East, 180° = South, 270° = West), y: top/bottom position in degrees (-90° = bottom, 0° = front, 90° = top), z: zoom (0 = wide, 100 = zoomed in) }
getPictureOriginalHeading
Get capture orientation of current picture, based on its GPS.
Returns any Picture original heading in degrees (0 to 360°)
getPictureRelativeHeading
Computes the relative heading of currently selected picture. This gives the angle of capture compared to sequence path (vehicle movement).
Returns any Relative heading in degrees (-180 to 180)
clearPictureMetadataCache
Clears the Photo Sphere Viewer metadata cache. It is useful when current picture or sequence has changed server-side after first load.
setXYZ
Change the shown position in picture
Parameters
setHigherContrast
Enable or disable higher contrast on picture
Parameters
enable
boolean True to enable higher contrast
getTransitionDuration
Get the duration of stay on a picture during a sequence play.
Returns number The duration (in milliseconds)
setTransitionDuration
Changes the duration of stay on a picture during a sequence play.
Parameters
value
number The new duration (in milliseconds, between 100 and 3000)
showErrorOverlay
Display an error message to user on screen
Parameters
e
object The initial errorlabel
str The main error label to displaydissmisable
boolean Is error dissmisable
Editor
Extends CoreView
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 class functions as well.
Parameters
container
(string | Element) The DOM element to create viewer intoendpoint
string URL to API to use (must be a STAC API)-
options
object? View options. (optional, default{}
)options.selectedSequence
string The ID of sequence to highlight on load. Must be always defined.options.selectedPicture
string? The ID of picture to highlight on load (defaults to none)options.fetchOptions
object Set custom options for fetch calls made against API (same syntax as fetch options parameter) (optional, defaultnull
)options.raster
object? The MapLibre raster source for aerial background. This must be a JSON object following MapLibre raster source definition.options.background
string? Choose default map background to display (streets or aerial, if raster aerial background available). Defaults to street.options.style
(string | object)? The map's MapLibre style. This can be an a JSON object conforming to the schema described in the MapLibre Style Specification, or a URL string pointing to one.
Properties
previewSequenceHeadingChange
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.
Parameters
relHeading
number? 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.
StandaloneMap
Extends CoreView
The standalone map viewer allows to see STAC pictures data as a map. It only embeds a map (no 360° pictures viewer) with a minimal picture preview (thumbnail).
Note that you can use any of the CoreView class functions as well.
Parameters
container
(string | Element) The DOM element to create viewer intoendpoint
string URL to API to use (must be a STAC API)-
options
object? Map options. Various settings can be passed, either the ones defined here, or any of MapLibre GL settings. (optional, default{}
)options.selectedSequence
string? The ID of sequence to highlight on load (defaults to none)options.selectedPicture
string? The ID of picture to highlight on load (defaults to none)options.fetchOptions
object Set custom options for fetch calls made against API (same syntax as fetch options parameter) (optional, defaultnull
)options.minZoom
number The minimum zoom level of the map (0-24). (optional, default0
)options.maxZoom
number The maximum zoom level of the map (0-24). (optional, default24
)options.style
(string | object)? The map's MapLibre style. This can be an a JSON object conforming to the schema described in the MapLibre Style Specification, or a URL string pointing to one.options.center
external:maplibre-gl.LngLatLike The initial geographical centerpoint of the map. Ifcenter
is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to[0, 0]
Note: MapLibre GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON. (optional, default[0,0]
)options.zoom
number The initial zoom level of the map. Ifzoom
is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to0
. (optional, default0
)options.bounds
external:maplibre-gl.LngLatBoundsLike? The initial bounds of the map. Ifbounds
is specified, it overridescenter
andzoom
constructor options.options.users
Array<string>? The IDs of users whom data should appear on map (defaults to all)
Properties
map
Map The map widget
destroy
Ends all form of life in this object.
This is useful for Single Page Applications (SPA), to remove various event listeners.
autoDetectLocale
Find best matching language regarding of list of supported languages and browser accepted languages
Parameters
supportedTranslations
Array\List of supported languages fallback
str The fallback language
Returns any The best matching language
getCookie
Get a cookie value
Parameters
name
str The cookie name
Returns str The cookie value, or null if not found
getUserAccount
Checks if an user account exists
Returns object Object like {"id", "name"} or null if no authenticated account
Viewer
Extends CoreView
Viewer is the main component of Panoramax JS library, showing pictures and map.
Note that you can use any of the CoreView class functions as well.
Parameters
container
(string | Element) The DOM element to create viewer intoendpoint
string URL to API to use (must be a STAC API)-
options
object? Viewer options (optional, default{}
)options.selectedPicture
string? Initial picture identifier to displayoptions.position
Array<number>? Initial position to go to (in [lat, lon] format)options.hash
boolean Enable URL hash settings (optional, defaulttrue
)options.lang
string? Override language to use (defaults to navigator language, or English if translation not available)options.transition
int Duration of stay on a picture during sequence play (excludes loading time) (optional, default250
)options.fetchOptions
object Set custom options for fetch calls made against API (same syntax as fetch options parameter) (optional, defaultnull
)options.users
(string | Array<string>)? The IDs of users whom data should appear on map (defaults to all). Only works with API having a "user-xyz" or "user-xyz-style" endpoint.options.picturesNavigation
string? The allowed navigation between pictures ("any": no restriction (default), "seq": only pictures in same sequence, "pic": only selected picture)-
options.map
(boolean | object) Enable contextual map for locating pictures. Setting to true or passing an object enables the map. Various settings can be passed, either the ones defined here, or any of MapLibre GL settings (optional, defaultfalse
)options.map.startWide
boolean? Show the map as main element at startup (defaults to false, viewer is wider at start)options.map.minZoom
number The minimum zoom level of the map (0-24). (optional, default0
)options.map.maxZoom
number The maximum zoom level of the map (0-24). (optional, default24
)options.map.raster
object? The MapLibre raster source for aerial background. This must be a JSON object following MapLibre raster source definition.options.map.center
external:maplibre-gl.LngLatLike The initial geographical centerpoint of the map. Ifcenter
is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to[0, 0]
Note: MapLibre GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON. (optional, default[0,0]
)options.map.zoom
number The initial zoom level of the map. Ifzoom
is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to0
. (optional, default0
)options.map.bounds
external:maplibre-gl.LngLatBoundsLike? The initial bounds of the map. Ifbounds
is specified, it overridescenter
andzoom
constructor options.-
options.map.geocoder
object? Optional geocoder settingsoptions.map.geocoder.engine
string? Set the geocoder engine to use (nominatim, ban) *options.map.background
string? Choose default map background to display (streets or aerial, if raster aerial background available). Defaults to street. *options.map.theme
string The colouring scheme to use for pictures and sequences on map (default, age, type) (optional, defaultdefault
)options.style
(string | object)? The map's MapLibre style. This can be an a JSON object conforming to the schema described in the MapLibre Style Specification, or a URL string pointing to one.options.widgets
object? Settings related to viewer buttons and widgets
-
options.widgets.editIdUrl
string? URL to the OpenStreetMap iD editor (defaults to OSM.org iD instance) options.widgets.customWidget
(string | Element)? A user-defined widget to add (will be shown over "Share" button)options.widgets.mapAttribution
string? Override the default map attribution (read from MapLibre style)options.widgets.iframeBaseURL
string? Set a custom base URL for the "Share as iframe" menu (defaults to current page)
Properties
destroy
Ends all form of life in this object.
This is useful for Single Page Applications (SPA), to remove various event listeners.
refreshPSV
Force reload of texture and tiles in Photo Sphere Viewer.
setPopup
Change full-page popup visibility and content
Parameters
visible
boolean True to make it appearcontent
(string | Array<Element>)? The new popup content (optional, defaultnull
)
playSequence
Goes continuously to next picture in sequence as long as possible
stopSequence
Stops playing current sequence
isSequencePlaying
Is there any sequence being played right now ?
Returns boolean True if sequence is playing
toggleSequencePlaying
Starts/stops the reading of pictures in a sequence
moveCenter
Move the view of main component to its center. For map, center view on selected picture. For picture, center view on image center.
moveLeft
Moves the view of main component slightly to the left.
moveRight
Moves the view of main component slightly to the right.
moveUp
Moves the view of main component slightly to the top.
moveDown
Moves the view of main component slightly to the bottom.
isMapWide
Is the map shown as main element instead of viewer (wide map mode) ?
Returns boolean True if map is wider than viewer
getPicturesNavigation
Get current pictures navigation mode.
Returns string The picture navigation mode ("any": no restriction, "seq": only pictures in same sequence, "pic": only selected picture)
setPicturesNavigation
Switch the allowed navigation between pictures.
Parameters
pn
string The picture navigation mode ("any": no restriction, "seq": only pictures in same sequence, "pic": only selected picture)
toggleJOSMLive
Enable or disable JOSM live editing using Remote
Parameters
enabled
boolean Set to true to enable JOSM live
Returns Promise Resolves on JOSM live being enabled or disabled
setFocus
Change the viewer focus (either on picture or map)
Parameters
focus
string The object to focus on (map, pic)skipEvent
boolean True to not send focus-changed event (optional, defaultfalse
)
toggleFocus
Toggle the viewer focus (either on picture or map)
setUnfocusedVisible
Change the visibility of reduced component (picture or map)
Parameters
visible
boolean True to make reduced component visible
toggleUnfocusedVisible
Toggle the visibility of reduced component (picture or map)
setFilters
Change the map filters
Parameters
-
filters
object Filtering valuesfilters.minDate
string? Start date for pictures (format YYYY-MM-DD)filters.maxDate
string? End date for pictures (format YYYY-MM-DD)filters.type
string? Type of picture to keep (flat, equirectangular)filters.camera
string? Camera make and model to keepfilters.theme
string? Map theme to useskipZoomIn
boolean If true, doesn't force zoom in to map level >= 7 (optional, defaultfalse
)
sequence-playing
Event for sequence starting to play
sequence-stopped
Event for sequence stopped playing
pictures-navigation-changed
Event for pictures navigation mode change
Type: object
Properties
josm-live-enabled
Event for JOSM live enabled
josm-live-disabled
Event for JOSM live disabled
focus-changed
Event for focus change (either map or picture is shown wide)
Type: object
Properties
filters-changed
Event for filters changes
Type: object
Properties
-
detail
object Event information