Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Viewer

class

Viewer

classdesc

The Viewer object represents the navigable image viewer. Create a Viewer by specifying a container, client ID, image key and other options. The viewer exposes methods and events for programmatic interaction.

In the case of asynchronous methods, MapillaryJS returns promises to the results. Notifications are always emitted through JavaScript events.

The viewer works with a few different coordinate systems.

Container pixel coordinates

Pixel coordinates are coordinates on the viewer container. The origin is in the top left corner of the container. The axes are directed according to the following for a viewer container with a width of 640 pixels and height of 480 pixels.

(0,0)                          (640, 0)
     +------------------------>
     |
     |
     |
     v                        +
(0, 480)                       (640, 480)

Basic image coordinates

Basic image coordinates represents points in the original image adjusted for orientation. They range from 0 to 1 on both axes. The origin is in the top left corner of the image and the axes are directed according to the following for all image types.

(0,0)                          (1, 0)
     +------------------------>
     |
     |
     |
     v                        +
(0, 1)                         (1, 1)

For every camera viewing direction it is possible to convert between these two coordinate systems for the current node. The image can be panned and zoomed independently of the size of the viewer container resulting in different conversion results for different viewing directions.

Hierarchy

  • EventEmitter
    • Viewer

Index

Constructors

constructor

  • new Viewer(id: string, clientId: string, key?: string, options?: IViewerOptions, token?: string): Viewer
  • Create a new viewer instance.

    description

    It is possible to initialize the viewer with or without a key.

    When you want to show a specific image in the viewer from the start you should initialize it with a key.

    When you do not know the first image key at implementation time, e.g. in a map-viewer application you should initialize the viewer without a key and call moveToKey instead.

    When initializing with a key the viewer is bound to that key until the node for that key has been successfully loaded. Also, a cover with the image of the key will be shown. If the data for that key can not be loaded because the key is faulty or other errors occur it is not possible to navigate to another key because the viewer is not navigable. The viewer becomes navigable when the data for the key has been loaded and the image is shown in the viewer. This way of initializing the viewer is mostly for embedding in blog posts and similar where one wants to show a specific image initially.

    If the viewer is initialized without a key (with null or undefined) it is not bound to any particular key and it is possible to move to any key with viewer.moveToKey("<my-image-key>"). If the first move to a key fails it is possible to move to another key. The viewer will show a black background until a move succeeds. This way of intitializing is suited for a map-viewer application when the initial key is not known at implementation time.

    example
    var viewer = new Mapillary.Viewer("<element-id>", "<client-id>", "<image-key>");

    Parameters

    • id: string

      Required id of a DOM element which will be transformed into the viewer.

    • clientId: string

      Required Mapillary API ClientID. Can be obtained from https://www.mapillary.com/app/settings/developers.

    • Optional key: string

      Optional image-key to start from. The key can be any Mapillary image. If a key is provided the viewer is bound to that key until it has been fully loaded. If null is provided no image is loaded at viewer initialization and the viewer is not bound to any particular key. Any image can then be navigated to with e.g. viewer.moveToKey("<my-image-key>").

    • Optional options: IViewerOptions

      Optional configuration object specifing Viewer's and the components' initial setup.

    • Optional token: string

      Optional bearer token for API requests of protected resources.

    Returns Viewer

Events

Static bearingchanged

bearingchanged: string = "bearingchanged"

Fired when the viewing direction of the camera changes.

description

Related to the computed compass angle (Node.computedCA) from SfM, not the original EXIF compass angle.

type

{number} bearing - Value indicating the current bearing measured in degrees clockwise with respect to north.

Static click

click: string = "click"

Fired when a pointing device (usually a mouse) is pressed and released at the same point in the viewer.

type

IViewerMouseEvent event - Viewer mouse event data.

Static contextmenu

contextmenu: string = "contextmenu"

Fired when the right button of the mouse is clicked within the viewer.

type

IViewerMouseEvent event - Viewer mouse event data.

Static dblclick

dblclick: string = "dblclick"

Fired when a pointing device (usually a mouse) is clicked twice at the same point in the viewer.

type

IViewerMouseEvent event - Viewer mouse event data.

Static loadingchanged

loadingchanged: string = "loadingchanged"

Fired when the viewer is loading more data.

type

{boolean} loading - Boolean indicating whether the viewer is loading.

Static mousedown

mousedown: string = "mousedown"

Fired when a pointing device (usually a mouse) is pressed within the viewer.

type

IViewerMouseEvent event - Viewer mouse event data.

Static mousemove

mousemove: string = "mousemove"

Fired when a pointing device (usually a mouse) is moved within the viewer.

description

Will not fire when the mouse is actively used, e.g. for drag pan.

type

IViewerMouseEvent event - Viewer mouse event data.

Static mouseout

mouseout: string = "mouseout"

Fired when a pointing device (usually a mouse) leaves the viewer's canvas.

type

IViewerMouseEvent event - Viewer mouse event data.

Static mouseover

mouseover: string = "mouseover"

Fired when a pointing device (usually a mouse) is moved onto the viewer's canvas.

type

IViewerMouseEvent event - Viewer mouse event data.

Static mouseup

mouseup: string = "mouseup"

Fired when a pointing device (usually a mouse) is released within the viewer.

type

IViewerMouseEvent event - Viewer mouse event data.

Static moveend

moveend: string = "moveend"

Fired when the viewer motion stops and it is in a fixed position with a fixed point of view.

Static movestart

movestart: string = "movestart"

Fired when the motion from one view to another start, either by changing the position (e.g. when changing node) or when changing point of view (e.g. by interaction such as pan and zoom).

Static navigablechanged

navigablechanged: string = "navigablechanged"

Fired when the navigable state of the viewer changes.

description

The navigable state indicates if the viewer supports moving, i.e. calling the moveToKey, moveDir and moveCloseTo methods. The viewer will not be in a navigable state if the cover is activated and the viewer has been supplied a key. When the cover is deactivated or activated without being supplied a key it will be navigable.

type

{boolean} navigable - Boolean indicating whether the viewer is navigable.

Static nodechanged

nodechanged: string = "nodechanged"

Fired every time the viewer navigates to a new node.

type

Node node - Current node.

Static sequenceedgeschanged

sequenceedgeschanged: string = "sequenceedgeschanged"

Fired every time the sequence edges of the current node changes.

type

IEdgeStatus status - The edge status object.

Static spatialedgeschanged

spatialedgeschanged: string = "spatialedgeschanged"

Fired every time the spatial edges of the current node changes.

type

IEdgeStatus status - The edge status object.

Accessors

isNavigable

  • get isNavigable(): boolean
  • Return a boolean indicating if the viewer is in a navigable state.

    description

    The navigable state indicates if the viewer supports moving, i.e. calling the moveToKey, moveDir and moveCloseTo methods or changing the authentication state, i.e. calling setAuthToken. The viewer will not be in a navigable state if the cover is activated and the viewer has been supplied a key. When the cover is deactivated or the viewer is activated without being supplied a key it will be navigable.

    Returns boolean

    Boolean indicating whether the viewer is navigable.

Methods

activateCombinedPanning

  • activateCombinedPanning(): void
  • Activate the combined panning functionality.

    description

    The combined panning functionality is active by default.

    Returns void

activateComponent

  • activateComponent(name: string): void
  • Activate a component.

    example
    viewer.activateComponent("marker");

    Parameters

    • name: string

      Name of the component which will become active.

    Returns void

activateCover

  • activateCover(): void
  • Activate the cover (deactivates all other components).

    Returns void

deactivateCombinedPanning

  • deactivateCombinedPanning(): void
  • Deactivate the combined panning functionality.

    description

    Deactivating the combined panning functionality could be needed in scenarios involving sequence only navigation.

    Returns void

deactivateComponent

  • deactivateComponent(name: string): void
  • Deactivate a component.

    example
    viewer.deactivateComponent("mouse");

    Parameters

    • name: string

      Name of component which become inactive.

    Returns void

deactivateCover

  • deactivateCover(): void
  • Deactivate the cover (activates all components marked as active).

    Returns void

fire

  • fire(eventType: string, data: any): void
  • Parameters

    • eventType: string
    • data: any

    Returns void

getBearing

  • getBearing(): when.Promise<number>
  • Get the bearing of the current viewer camera.

    description

    The bearing depends on how the camera is currently rotated and does not correspond to the compass angle of the current node if the view has been panned.

    Bearing is measured in degrees clockwise with respect to north.

    example
    viewer.getBearing().then((b) => { console.log(b); });

    Returns when.Promise<number>

    Promise to the bearing of the current viewer camera.

getCenter

  • getCenter(): when.Promise<number[]>
  • Get the basic coordinates of the current image that is at the center of the viewport.

    description

    Basic coordinates are 2D coordinates on the [0, 1] interval and have the origin point, (0, 0), at the top left corner and the maximum value, (1, 1), at the bottom right corner of the original image.

    example
    viewer.getCenter().then((c) => { console.log(c); });

    Returns when.Promise<number[]>

    Promise to the basic coordinates of the current image at the center for the viewport.

getComponent

  • getComponent<TComponent>(name: string): TComponent
  • Get a component.

    example
    var mouseComponent = viewer.getComponent("mouse");

    Type parameters

    • TComponent: Component<IComponentConfiguration>

    Parameters

    • name: string

      Name of component.

    Returns TComponent

    The requested component.

getContainer

  • getContainer(): HTMLElement
  • Returns the viewer's containing HTML element.

    Returns HTMLElement

    The viewer's container.

getZoom

  • getZoom(): when.Promise<number>
  • Get the image's current zoom level.

    example
    viewer.getZoom().then((z) => { console.log(z); });

    Returns when.Promise<number>

    Promise to the viewers's current zoom level.

moveCloseTo

  • moveCloseTo(lat: number, lon: number): when.Promise<Node>
  • Move close to given latitude and longitude.

    description

    Because the method propagates IO errors, these potential errors need to be handled by the method caller (see example).

    throws

    {Error} If no nodes exist close to provided latitude longitude.

    throws

    {Error} Propagates any IO errors to the caller.

    throws

    {Error} When viewer is not navigable.

    throws

    AbortMapillaryError When a subsequent move request is made before the move close to call has completed.

    example
    viewer.moveCloseTo(0, 0).then(
        (n) => { console.log(n); },
        (e) => { console.error(e); });

    Parameters

    • lat: number

      Latitude, in degrees.

    • lon: number

      Longitude, in degrees.

    Returns when.Promise<Node>

    Promise to the node that was navigated to.

moveDir

  • Navigate in a given direction.

    description

    This method has to be called through EdgeDirection enumeration as in the example.

    throws

    {Error} If the current node does not have the edge direction or the edges has not yet been cached.

    throws

    {Error} Propagates any IO errors to the caller.

    throws

    {Error} When viewer is not navigable.

    throws

    AbortMapillaryError When a subsequent move request is made before the move dir call has completed.

    example
    viewer.moveDir(Mapillary.EdgeDirection.Next).then(
        (n) => { console.log(n); },
        (e) => { console.error(e); });

    Parameters

    Returns when.Promise<Node>

    Promise to the node that was navigated to.

moveToKey

  • moveToKey(key: string): when.Promise<Node>
  • Navigate to a given image key.

    throws

    {Error} Propagates any IO errors to the caller.

    throws

    {Error} When viewer is not navigable.

    throws

    AbortMapillaryError When a subsequent move request is made before the move to key call has completed.

    example
    viewer.moveToKey("<my key>").then(
        (n) => { console.log(n); },
        (e) => { console.error(e); });

    Parameters

    • key: string

      A valid Mapillary image key.

    Returns when.Promise<Node>

    Promise to the node that was navigated to.

off

  • off(eventType: string, fn: any): void
  • Unsubscribe from an event by its name.

    Parameters

    • eventType: string

      The name of the event to subscribe to.

    • fn: any

      The handler to remove.

    Returns void

on

  • on(eventType: string, fn: any): void
  • Subscribe to an event by its name.

    Parameters

    • eventType: string

      The name of the event to subscribe to.

    • fn: any

      The handler called when the event occurs.

    Returns void

projectFromBasic

  • projectFromBasic(basicPoint: number[]): when.Promise<number[]>
  • Project basic image coordinates for the current node to canvas pixel coordinates.

    description

    The basic image coordinates may not always correspond to a pixel point that lies in the visible area of the viewer container.

    example
    viewer.projectFromBasic([0.3, 0.7])
        .then((pixelPoint) => { console.log(pixelPoint); });

    Parameters

    • basicPoint: number[]

      Basic images coordinates to project.

    Returns when.Promise<number[]>

    Promise to the pixel coordinates corresponding to the basic image point.

resize

  • resize(): void
  • Detect the viewer's new width and height and resize it.

    description

    The components will also detect the viewer's new size and resize their rendered elements if needed.

    example
    viewer.resize();

    Returns void

setAuthToken

  • setAuthToken(token?: string): when.Promise<void>
  • Set a bearer token for authenticated API requests of protected resources.

    description

    When the supplied token is null or undefined, any previously set bearer token will be cleared and the viewer will make unauthenticated requests.

    Calling setAuthToken aborts all outstanding move requests. The promises of those move requests will be rejected with a AbortMapillaryError the rejections need to be caught.

    Calling setAuthToken also resets the complete viewer cache so it should not be called repeatedly.

    throws

    {Error} When viewer is not navigable.

    example
    viewer.setAuthToken("<my token>")
        .then(() => { console.log("token set"); });

    Parameters

    • Optional token: string

    Returns when.Promise<void>

    Promise that resolves after token is set.

setCenter

  • setCenter(center: number[]): void
  • Set the basic coordinates of the current image to be in the center of the viewport.

    description

    Basic coordinates are 2D coordinates on the [0, 1] interval and has the origin point, (0, 0), at the top left corner and the maximum value, (1, 1), at the bottom right corner of the original image.

    example
    viewer.setCenter([0.5, 0.5]);

    Parameters

    • center: number[]

    Returns void

setFilter

  • Set the filter selecting nodes to use when calculating the spatial edges.

    description

    The following filter types are supported:

    Comparison

    ["==", key, value] equality: node[key] = value

    ["!=", key, value] inequality: node[key] ≠ value

    ["<", key, value] less than: node[key] < value

    ["<=", key, value] less than or equal: node[key] ≤ value

    [">", key, value] greater than: node[key] > value

    [">=", key, value] greater than or equal: node[key] ≥ value

    Set membership

    ["in", key, v0, ..., vn] set inclusion: node[key] ∈ {v0, ..., vn}

    ["!in", key, v0, ..., vn] set exclusion: node[key] ∉ {v0, ..., vn}

    Combining

    ["all", f0, ..., fn] logical AND: f0 ∧ ... ∧ fn

    A key must be a string that identifies a property name of a simple Node property. A value must be a string, number, or boolean. Strictly-typed comparisons are used. The values f0, ..., fn of the combining filter must be filter expressions.

    Clear the filter by setting it to null or empty array.

    example
    viewer.setFilter(["==", "sequenceKey", "<my sequence key>"]);

    Parameters

    Returns when.Promise<void>

    Promise that resolves after filter is applied.

setRenderMode

  • Set the viewer's render mode.

    example
    viewer.setRenderMode(Mapillary.RenderMode.Letterbox);

    Parameters

    Returns void

setTransitionMode

  • Set the viewer's transition mode.

    example
    viewer.setTransitionMode(Mapillary.TransitionMode.Instantaneous);

    Parameters

    Returns void

setZoom

  • setZoom(zoom: number): void
  • Set the image's current zoom level.

    description

    Possible zoom level values are on the [0, 3] interval. Zero means zooming out to fit the image to the view whereas three shows the highest level of detail.

    example
    viewer.setZoom(2);

    Parameters

    • zoom: number

    Returns void

unproject

  • unproject(pixelPoint: number[]): when.Promise<ILatLon>
  • Unproject canvas pixel coordinates to an ILatLon representing geographical coordinates.

    description

    The pixel point may not always correspond to geographical coordinates. In the case of no correspondence the returned value will be null.

    example
    viewer.unproject([100, 100])
        .then((latLon) => { console.log(latLon); });

    Parameters

    • pixelPoint: number[]

      Pixel coordinates to unproject.

    Returns when.Promise<ILatLon>

    Promise to the latLon corresponding to the pixel point.

unprojectToBasic

  • unprojectToBasic(pixelPoint: number[]): when.Promise<number[]>
  • Unproject canvas pixel coordinates to basic image coordinates for the current node.

    description

    The pixel point may not always correspond to basic image coordinates. In the case of no correspondence the returned value will be null.

    example
    viewer.unprojectToBasic([100, 100])
        .then((basicPoint) => { console.log(basicPoint); });

    Parameters

    • pixelPoint: number[]

      Pixel coordinates to unproject.

    Returns when.Promise<number[]>

    Promise to the basic coordinates corresponding to the pixel point.

Generated using TypeDoc