@mapbox/mapbox-gl-image-viewer

A generic Mapbox GL JS control for viewing and tagging images.

Setup

Add the JavaScript and CSS file from the package.

<script src="https://unpkg.com/@mapbox/mapbox-gl-image-viewer@1.0.11/dist/mapbox-gl-image-viewer.js" charset="utf-8"></script>
<link rel="stylesheet" href="https://unpkg.com/@mapbox/mapbox-gl-image-viewer@1.0.11/dist/mapbox-gl-image-viewer.css">

Or install the package from npm,

npm install --save @mapbox/mapbox-gl-image-viewer

and import the js and css files.

import MapboxImageViewer from '@mapbox/mapbox-gl-image-viewer/dist/mapbox-gl-image-viewer.js';
import '@mapbox/mapbox-gl-image-viewer/dist/mapbox-gl-image-viewer.css';

Quickstart

Create an instance of the control,

var imageViewer = new MapboxImageViewer({
  allowResize: true,
  allowTagCreate: true,
  allowTagDelete: true,
  allowTagSelect: true,
  defaultTags: ['trafficsign', 'stopsignal', 'noleftturn'],
  onTagCreate: function(tag) { console.log('created', tag); },
  onTagDelete: function(tag) { console.log('deleted', tag); },
  onTagSelect: function(tag) { console.log('selected', tag); },
});

and add it to the map.

map.addControl(imageViewer, 'bottom-left');

API

new MapboxImageViewer(config)

Create an instance of the image viewer. Returns imageViewer.

Configs:

• allowResize (boolean, default false) Allow image resizing?
• allowTagCreate (boolean, default false) Allow creating new tags?
• allowTagDelete (boolean, default false) Allow deleting existing tags?
• allowTagSelect (boolen, default false) Allow selecting tags?
• defaultTags (Array, default []) List of default tags that can be used when tagging.
• aspectRatio (number, default NaN) The aspect ratio of a tag. Free-form by default.
• onTagCreate (function, optional) Function called when a new tag is created. Receives a tag object.
• onTagDelete (function, optional) Function called when an existing tag is deleted. Receives a tag object.
• onTagSelect (function, optional) Function called when a tag is selected. Receives a tag object.

A tag object created by the control will be of the following structure.

{ id: 'b9bd77b70fd9285c0379e34deba33385', // unique id created for each tag
  x: 48, y: 86,                           // top-left coords of the tag wrt to the image
  width: 84, height: 84,                  // width and height of the tag
  name: 'trafficsign'                     // name, one of the set default tags
}

imageViewer.showImage(url, [tags])

Load an image and display it on the viewer. If an array of tags is provided, render them on the image.

imageViewer.showImage('http://placehold.it/350x350',
  [
    {id: 'b9bd77b70fd9285c0379e34deba33385', x: 48, y: 86, width: 84, height: 84, name: 'trafficsign'},
    {id: '0074efb305841c15a7f040442a4e3f14', x: 233, y: 26, width: 84, height: 84, name: 'stopsignal'},
    {id: '87f7dbd6e3b1156f6ffefe0f43ee1c9e', x: 217, y: 199, width: 116, height: 133, name: 'noleftturn'}
  ]
);

imageViewer.hideImage()

Hide the viewer.

Example

See example/index.html for a working example.