Skip to content

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 into
  • endpoint 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, default null)
    • 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 options
  • container 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, default null)
  • picId string? The picture UUID (optional, default null)
  • force boolean Force select even if already selected (optional, default false)

select

Event for sequence/picture selection

Type: object

Properties

  • detail object Event information

    • detail.seqId string The selected sequence ID
    • detail.picId string The selected picture ID (or null if not a precise picture clicked)
    • detail.prevSeqId string? The previously selected sequence ID (or null if none)
    • detail.prevPicId string? The previously selected picture ID (or null if none)

ready

Event for viewer being ready to use (API loaded)

broken

Event for viewer failing to initially load

Type: object

Properties

  • detail object Event information

    • detail.error string The user-friendly error message to display

map:background-changed

Event for map background changes

Type: object

Properties

  • detail object Event information

    • detail.background string? The new selected background (aerial, streets)

map:users-changed

Event for visible users changes

Type: object

Properties

  • detail object Event information

    • detail.usersIds Array<string>? The list of newly selected users

map:sequence-hover

Event when a sequence on map is hovered (not selected)

Type: object

Properties

  • detail object Event information

    • detail.seqId string The hovered sequence ID

map:sequence-click

Event when a sequence on map is clicked

Type: object

Properties

  • detail object Event information

    • detail.seqId string The clicked sequence ID
    • detail.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

    • detail.picId string The clicked picture ID
    • detail.seqId string The clicked picture's sequence ID
    • detail.feature object The GeoJSON feature of the picture

psv:picture-loading

Event for picture starting to load

Type: object

Properties

  • detail object Event information

    • detail.picId string The picture unique identifier
    • detail.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

    • detail.picId string The picture ID
    • detail.coordinates Array<number> [x,y] coordinates
    • detail.direction number The theorical picture orientation

psv:picture-preview-stopped

Event for end of picture preview

Type: object

Properties

  • detail object Event information

    • detail.picId string The picture ID

psv:view-rotated

Event for viewer rotation

Type: object

Properties

  • detail object Event information

    • 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 (between 0 and 100)

psv:picture-loaded

Event for picture load (low-resolution image is loaded)

Type: object

Properties

  • detail object Event information

    • detail.picId string The picture unique identifier
    • detail.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

  • detail object Event information

    • detail.picId string The picture unique identifier

psv:transition-duration-changed

Event for transition duration change

Type: object

Properties

  • detail object Event information

    • detail.duration string New duration (in milliseconds)

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 view
  • container 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 settings

      • options.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

  • visibleIds (string | Array<string>) The user layers IDs to display (optional, default [])

filterUserLayersContent

Filter the visible data content in all visible map layers

Parameters

  • dataType string sequences or pictures
  • filter object The MapLibre GL filter rule to apply

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 view
  • container Element The DOM element to create into

  • options object? The viewer options. Can be any of Photo Sphere Viewer options (optional, default {})

    • options.transitionDuration number? The number of milliseconds the transition animation should be.
    • options.shouldGoFast function? Function returning a boolean to indicate if we may skip loading HD images.

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

  • x number X position (in degrees)
  • y number Y position (in degrees)
  • z number Z position (0-100)

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 error
  • label str The main error label to display
  • dissmisable 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 into
  • endpoint 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, default null)
    • 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

  • map Map The map widget
  • psv Photo The photo widget

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 into
  • endpoint 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, default null)
    • options.minZoom number The minimum zoom level of the map (0-24). (optional, default 0)
    • options.maxZoom number The maximum zoom level of the map (0-24). (optional, default 24)
    • 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. If center 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. If zoom 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. (optional, default 0)
    • options.bounds external:maplibre-gl.LngLatBoundsLike? The initial bounds of the map. If bounds is specified, it overrides center and zoom 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 into
  • endpoint string URL to API to use (must be a STAC API)

  • options object? Viewer options (optional, default {})

    • options.selectedPicture string? Initial picture identifier to display
    • options.position Array<number>? Initial position to go to (in [lat, lon] format)
    • options.hash boolean Enable URL hash settings (optional, default true)
    • 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, default 250)
    • options.fetchOptions object Set custom options for fetch calls made against API (same syntax as fetch options parameter) (optional, default null)
    • 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, default false)

      • 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, default 0)
      • options.map.maxZoom number The maximum zoom level of the map (0-24). (optional, default 24)
      • 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. If center 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. If zoom 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. (optional, default 0)
      • options.map.bounds external:maplibre-gl.LngLatBoundsLike? The initial bounds of the map. If bounds is specified, it overrides center and zoom constructor options.

      • options.map.geocoder object? Optional geocoder settings

        • options.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, default default)
          • 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

  • map Map The map widget
  • psv Photo The photo widget

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

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, default false)

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 values

    • filters.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 keep
    • filters.theme string? Map theme to use
    • skipZoomIn boolean If true, doesn't force zoom in to map level >= 7 (optional, default false)

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

  • detail object Event information

    • detail.value string New mode (any, pic, seq)

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

  • detail object Event information

    • detail.focus string Component now focused on (map, pic)

filters-changed

Event for filters changes

Type: object

Properties

  • detail object Event information

    • detail.minDate string? The minimum date in time range (ISO format)
    • detail.maxDate string? The maximum date in time range (ISO format)
    • detail.type string? Camera type (equirectangular, flat, null/empty string for both)
    • detail.camera string? Camera make and model
    • detail.theme string? Map theme