npm package: @mapbox/mapbox-gl-image-viewer
Description: A image viewer control for Mapbox GL JS
Latest version: 1.1.0

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

## Setup

Add the JavaScript and CSS file from the package.

```html
<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,

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

and import the js and css files.

```js
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,

```js
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.

```js
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<string>, 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.

```js
{ 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.

```js
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](/example/index.html) for a working example.