v2.x

MapillaryJS `v2.x` Migration Guide#

This page describes how to migrate from MapillaryJS v1.x to MapillaryJS v2.x.

General#

v2.x has a completely rewritten graph structure and IO handling. The graph was rewritten to, among other things, load nodes faster when using the viewer.move* methods.

The requirements on the new graph meant breaking changes to the MapillaryJS API. In addition to the graph related changes some other breaking changes have been introduced as well.

Edge handling#

`v1.x`#

In v1.x the edges were always cached for nodes retrieved from the nodechanged event. The properties related to edge handling for the node where the following:

edges: IEdge[]edgesCached: boolean

Here, the edges array was always guaranteed to be populated when retrieved from the node of the nodechanged event. The edges array could be traversed immediately.

`v2.x`#

In v2.x, the graph creation is changed in a way that does not guarantee that the edges have been determined for the current node when it is retrieved from the nodechanged event. The edges have also been separated into two different entities, sequence and spatial edges. The different entities will be retrieved asyncronously and may be set at different times. Therefore, in v2.x, the node properties related to edges are the following:

sequenceEdges: IEdgeStatussequenceEdges$: Observable<IEdgeStatus>
spatialEdges: IEdgeStatusspatialEdges$: Observable<IEdgeStatus>

The edge status is like so:

interface IEdgeStatus {  cached: boolean;  edges: IEdge[];}

To simplify working with the edges the sequenceedgeschanged and spatialedgeschanged events on the Viewer should be used.

In the same way as before, the viewer will emit a nodechanged event every time the current node changes. Immediately after the nodechanged event it will emit the sequenceedgeschanged and spatialedgeschanged events containing the current edge statuses. At this point the edges may or may not be cached. If the sequence or spatial edges for the current node are cached or changed at a later point in time the sequenceedgeschanged and spatialedgeschanged events will fire respectively.

The sequenceedgeschanged and spatialedgeschanged events always emit edge status objects related to the current node retrieved from the nodechanged event, never for any other nodes.

Subscribing to the sequenceedgeschanged and spatialedgeschanged events is done in the following way:

viewer.on(Mapillary.Viewer.sequenceedgeschanged, function(status) { <do something>; });viewer.on(Mapillary.Viewer.spatialedgeschanged, function(status) { <do something>; });

Node properties#

Apart from the edge handling described above the status of the new node class is the following:

Identical properties#

`v1.x` & `v2.x`
`ca`
`capturedAt`
`fullPano`
`image`
`key`
`latLon`
`loadStatus`
`merged`
`mesh`
`pano`

Changed properties#

`v1.x`	`v2.x`
`apiNavImIm.atomic_scale`	`scale`
`apiNavImIm.ca`	`originalCA`
`apiNavImIm.calt`	`alt`
`apiNavImIm.camera_mode`	`scale`
`apiNavImIm.captured_at`	`capturedAt`
`apiNavImIm.cca`	`computedCA`
`apiNavImIm.cfocal`	`focal`
`apiNavImIm.clat`	`computedLatLon.lat`
`apiNavImIm.clon`	`computedLatLon.lon`
`apiNavImIm.gpano`	`gpano`
`apiNavImIm.height`	`height`
`apiNavImIm.key`	`key`
`apiNavImIm.lat`	`originalLatLon.lat`
`apiNavImIm.lon`	`originalLatLon.lon`
`apiNavImIm.merge_cc`	`mergeCC`
`apiNavImIm.merge_version`	`mergeVersion`
`apiNavImIm.orientation`	`orientation`
`apiNavImIm.rotation`	`rotation`
`apiNavImIm.user`	`username`
`apiNavImIm.width`	`width`
`sequence.key`	`sequenceKey`

Removed properties#

`v1.x`
`apiNavImIm`
`apiNavImIm.camera_mode`
`apiNavImIm.fmm35`
`hs`
`sequence`
`worthy`

New properties#

`v2.x`
`assetsCached`
`userKey`

Navigator failure cases#

When the Viewer.moveDir and Viewer.moveCloseTo methods are called there may not be a valid result. In that case, both methods throw errors that need to be handled by the caller.

Whenever any of the Viewer.moveToKey, Viewer.moveDir or Viewer.moveCloseTo methods encounter an IO related problem the error will propagate to the caller.

Rotation edge direction#

The EdgeDirection.RotateLeft and EdgeDirection.RotateRight enumeration values have been removed.

Component initialization#

The component options have been broken out from the regular viewer options.

v1.x:

var mly = new Mapillary.Viewer(  'mly',  '<your client id>',  '<your image key for initializing the viewer>',  {    baseImageSize: Mapillary.ImageSize.Size320,    cache: true,    keyboard: false,    sequence: {      maxWidth: 150,      minWidth: 80,    },    renderMode: Mapillary.RenderMode.Fill,  },);

v2.x:

var mly = new Mapillary.Viewer(  'mly',  '<your client id>',  '<your image key for initializing the viewer>',  {    baseImageSize: Mapillary.ImageSize.Size320,    component: {      cache: true,      keyboard: false,      sequence: {        maxWidth: 150,        minWidth: 80,      },    },    renderMode: Mapillary.RenderMode.Fill,  },);

Image plane component#

The image plane component has been renamed:

`v1.x`	`v2.x`
`imageplane`	`imagePlane`

This affects component initialization and the component API on the viewer.

Render mode#

RenderMode.Fill is now the default render mode (instead of RenderMode.Letterbox) when creating a new viewer instance.

Auth removed#

The deprecated Viewer.Auth method has been removed.

Renamed distribution files#

The distribution files have been renamed according to the following:

`v1.x`	`v2.x`
`mapillary-js.js`	`mapillary.js`
`mapillary-js.min.js`	`mapillary.min.js`
`mapillary-js.min.css`	`mapillary.min.css`

MapillaryJS v2.x Migration Guide#