mapbox-controls

« all controls

🏙️ @mapbox-controls/image

Control to move, scale, rotate image (raster layer) on top of a map. Very handy to represent information from the raster to geojson, for example, the contours of buildings.

npm i @mapbox-controls/image

import ImageControl from '@mapbox-controls/image';
import '@mapbox-controls/image/src/index.css';

const imageControl = new ImageControl();
map.addControl(imageControl, 'bottom-right');

Options

export type ControlOptions = {
    removeButton?: boolean;
};

Events

event	description
image.select	selected new image
image.deselect	image was deselected
image.mode	transform mode was changed
image.update	position was updated
image.add	new image added
image.remove	image removed

Methods

Methods are useful for programmatic control (when option invisible is true):

• addFile(file: File, coordinates?: [number, number][] | undefined): Promise<string>; - add new image by file. raster id is returned
• addUrl(url: string, coordinates?: [number, number][] | undefined): Promise<string>; - add new image by url. raster id is returned
• setLock: (id: string, isLocked: boolean) => void; - lock or unlock image. locked image can’t be selected
• removeRaster: () => void; - removes selected raster from the map

If image was added without coordinates parameter, the image is scaled down to be fully visible and placed at the center of the viewport.

Other methods may help to use this control without buttons, these methods are described in type definitions .d.ts.

Change paint properties

Paint properties can be changed dynamically. Below is an example how to control image opacity by slider (full implementation is available in preview).

map.on('image.select', ({ id }) => {
  const rasterLayerId = image.rasters[id].rasterLayer.id;
  const range = document.createElement('input');
  range.style.position = 'absolute';
  range.style.left = '50%';
  range.style.transform = 'translateX(-50%)';
  range.style.bottom = '16px';
  range.type = 'range';
  range.min = 0;
  range.step = 0.05;
  range.max = 1;
  range.value = map.getPaintProperty(rasterLayerId, 'raster-opacity');
  range.addEventListener('input', () => {
    map.setPaintProperty(rasterLayerId, 'raster-opacity', Number(range.value));
  });
  document.body.appendChild(range);
  map.once('image.deselect', () => {
    document.body.removeChild(range);
  });
});