mapbox / mapbox-gl-draw

Draw tools for mapbox-gl-js

@mapbox/mapbox-gl-draw

Adds support for drawing and editing features on mapbox-gl.js maps. See a live example here

Requires mapbox-gl-js.

If you are developing with mapbox-gl-draw, see API.md for documentation.

Installing

npm install @mapbox/mapbox-gl-draw

Draw ships with CSS, make sure you include it in your build.

Usage in your application

JavaScript

When using modules

import mapboxgl from 'mapbox-gl';
import MapboxDraw from "@mapbox/mapbox-gl-draw";

When using a CDN

<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.js'></script>

CSS

When using modules

import '@mapbox/mapbox-gl-draw/dist/mapbox-gl-draw.css'

When using CDN

<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.css' type='text/css' />

Typescript

Typescript definition files are available as part of the DefinitelyTyped package.

npm install @types/mapbox__mapbox-gl-draw

Example usage

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

var map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [40, -74.50],
  zoom: 9
});

var Draw = new MapboxDraw();

// Map#addControl takes an optional second argument to set the position of the control.
// If no position is specified the control defaults to `top-right`. See the docs
// for more details: https://docs.mapbox.com/mapbox-gl-js/api/#map#addcontrol

map.addControl(Draw, 'top-left');

map.on('load', function() {
  // ALL YOUR APPLICATION CODE
});

https://www.mapbox.com/mapbox-gl-js/example/mapbox-gl-draw/

See API.md for complete reference.

Enhancements and New Interactions

For additional functionality check out our list of custom modes.

Mapbox Draw accepts functionality changes after the functionality has been proven out via a custom mode. This lets users experiment and validate their mode before entering a review process, hopefully promoting innovation. When you write a custom mode, please open a PR adding it to our list of custom modes.

Developing and testing

Install dependencies, build the source files and crank up a server via:

git clone [email protected]:mapbox/mapbox-gl-draw.git
yarn install
yarn start & open "http://localhost:9967/debug/?access_token=<token>"

Testing

npm run test

Publishing

To GitHub and NPM:

npm version (major|minor|patch)
git push --tags
git push
npm publish

To CDN:

# make sure you are authenticated for AWS
git checkout v{x.y.z}
yarn install
yarn run prepublish
aws s3 cp --recursive --acl public-read dist s3://mapbox-gl-js/plugins/mapbox-gl-draw/v{x.y.z}

Update the version number in the GL JS example.

Naming actions

We're trying to follow standards when naming things. Here is a collection of links where we look for inspiration.

• https://turfjs.org
• https://shapely.readthedocs.io/en/latest/manual.html

mapbox-gl-draw's Issues

Advanced draw operations for squares

• Click and dragging with the alt key should draw a shape with fixed width+height with center pinning (i.e. the drawn layer expands in size across the canvas in both directions)
• Click and dragging with the shift key should draw a shape with fixed width+height with top-left pinning.

Use map.on('click'

Using the built-in on('click' event instead of catching click events on the map container will let gl-draw remove a bunch of code, including the homegrown mousePos utility fn

Remove store & undo/redo

I think that gl-draw should, at its core, only emit events. Undo/redo should be implemented outside of core.

Undo/Redo management

Should be built into the editor with Immutable.js wrapped into the current store. Some @tmcw reading material on the subject:

http://www.macwright.org/2015/05/18/practical-undo.html

As a UI I like the pattern used in inbox

robustify feature selection

This is wonky => https://github.com/mapbox/gl-draw/blob/master/src/draw.js#L167

Use ES6 classes + `import`s + `const`s + `let`s etc

Shape draw operations

• Click and dragging should draw a shape with variable width+height
• Click and dragging with the alt key should draw a shape with fixed width+height with center pinning (i.e. the drawn layer expands in size across the canvas in both directions)
• Click and dragging with the shift key should draw a shape with fixed width+height with top-left pinning.

ESC key should complete last current segment

Complete it as a lineString.

Return feature data when an edit point is selected

Via onfeaturesat. Enables:

• LineString and Polygon completion
• Putting features in edit mode

Better README.md

• Description
  • Overview
  • Version number
  • Testing badges
  • Link to live site (if applicable)
• Usage
  • How to use it with code samples
  • Links to documentation (if applicable)
• Running locally
  • How to run it locally
  • Include dependencies
• Testing
  • How to test it locally

Use prefix

The prefix module https://www.npmjs.com/package/prefix is a robust replacement for the prefix detection in this module

Remove guidelines when `disable` is called

Open source gl-draw

When this is the last issue to complete in https://github.com/mapbox/gl-draw/milestones/v1

Support passing .geojson to gl-draw

You should be able to select features

If you click on a feature, it should be restyled and selected.

• If the feature is a marker, it should be draggable #23
• If the feature is a polygon, it should be editable

When a person clicks on a marker and then drags the selected marker, the marker should move

The way I see this playing out is:

There are two states: edit & data (drawn or imported data)

• mousedown emits a function that calls map.featuresAt. This returns the feature under the mouse and removes it from data object and put's it in the edit object.
• mousedown + drag set's a key that enables mousemove
• mousemove calculates the coordinates of the markers placement on the map and updates the new coordinates to the edit object.
• mouseup unsets the key the enables mousemove, removes the feature from the edit object and updates the data object with the new coordinates.

cc @kelvinabrokwa

Initial line while drawing polygons is only rendered at high zoom levels

Implement drawing circles

What is the geojson output for a circle? a marker with a radius property?

Disable map dragging in draw & edit mode

For the life of me I can't figure out why disabling drag here is not working. It should and does call this method but map dragging is still enabled. It's possible mapbox-gl-js may be interfering with this.

cc @jfirebaugh @mourner on any insight.

Use mapbox gl instead of homegrown setoptions

https://github.com/mapbox/mapbox-gl-js/blob/master/js/util/util.js#L327-L345

This is exported by mapbox gl - we should use this instead of homegrowing setOptions

Keybindings to select draw tools

Passed as optional on initialization.

PRELAUNCH: Tests

Set up the framing for this in a53d849 might try using https://github.com/azer/prova instead of smokestack.

rewrite tests

I butchered them in #40

Some vertex markers (points) are only rendered at high zoom levels

This prevents editing certain nodes until you zoom in. Likely related to #46.

Shape edit operations

• Dragging a control point should resize a shape with the top right position pinned.
• Shift+Dragging a control point should resize a shape without pinning
• Dragging when a cursor is over a feature + within a variable radius should move a shape across the map.

Double-clicking and clicking on the first dot of a polygon should finish the polygon, but does not.

Resize handles should have grabbing-hand cursors

Resize handles should have special cursors for discoverability and to help users find their relatively small hit targets. This may be complicated by #22.

/cc @kelvinabrokwa @tmcw

Perfomance improvements

gl-draw, as is, is virtually unuseable. However, its a great test-case for gl-js on-the-fly rendering capabilities. That being said, there many optimizations in the javascript here that can ameliorate this.

To do:

• reduce calls to Immutable.toJS and Immutable.fromJS
• initialize all object members in constructor functions
• make variables monomorphic where possible
  • https://github.com/mapbox/gl-draw/blob/dev-pages/src/draw.js#L190-L191
• no longer used as of #51 make vertex finding for vertex drag less robust and less expensive
  • https://github.com/mapbox/gl-draw/blob/dev-pages/src/handlers/square.js#L97-L100
  • Math.sqrt(Math.pow(v.get(0) - coords[0], 2) + Math.pow(v.get(1) - coords[1], 2)) => Math.abs(v.get(0) - coords[0]) + Math.abs(v.get(1) - coords[1])

Upstream:

• check out zoom and pan implementations in mapbox-gl-js for tips and tricks on animation

[click => move => click] flow for drawing squares is broken

The underlying problem is that I naïvely choose the first item from the array returned by map.featuresAt

Add API.md

Generate this via jsdoc in the codebase.

Shift+Drag over the map canvas should put all features under selected bounds in edit mode

Holding shift should lock line drawing at 45 degree increments

Clicking on a polygon/linestring should put it in edit mode, which should show draggable vertices

If you click on an already-drawn polygon or line, it should give you the ability to change it or delete it.

• The polygon changes color
• The polygon also shows vertices
• The polygon can be deleted #5

add a "set geometry" API

Avoid using DOM elements

Many of the guides and intermediate drawing UI in gl-draw are constructed using divs and CSS: these should be implemented in GL land instead.

Guide line is not centered in vertex circle

The guide lines are starting from closer to the bottom than to the top.

move index.html into a debug folder

This doesn't need to be in the root directory. It is only used for development.

Requires mapboxgl global

https://github.com/mapbox/gl-draw/blob/dev-pages/index.js#L25 assumes that window.mapboxgl exists, which fails when using mapboxgl with browserify. Can we add mapboxgl as a dependency?

Control candidates

Leaflet Draw has 7 control elements:

• LineString
• Freeform polygon
• Square
• Circle
• Marker
• Edit existing
• Delete existing

It would ideal to narrow this toolchain.

---

I'd like to propose:

• Freeform pen with control interactions
• Circle
• Marker

Freeform pen would:

• Create a perfect square by holding the shift key (or one finger hold on touch)
• Complete a point by double clicking (likewise on touch) if the end point doesn't connect with the first it's a linestring.

To edit existing: If editing is enabled, touching or selecting an existing feature puts it in edit mode.
To delete existing: selecting an existing feature and hitting the escape key or touch and holding element for delete or edit options on mobile (this might be doable). Having some sort of undo flash display might be nice here too (something similar to the way inbox does it)

Simplification of midpoint calculation breaks down at large scales

The average is cheap but it just won't cut it -> https://github.com/mapbox/gl-draw/blob/dev-pages/src/edit_store.js#L85

Enable feature deletion

When a feature is in edit mode.

LineString translation broken

This makes it impossible to drag LineStrings

Drawing puts markers in the wrong place

New features should be drawn on top

Polygons aren't rerendered in edit mode at the end of drags

Hover styling

It would be nice if on hover, the feature that would be selected if clicked was styled differently.

replace NIH Control with mapboxgl.Control

mapbox gl already has a control class https://github.com/mapbox/mapbox-gl-js/blob/master/js/ui/control/control.js - we should use that instead of a homegrown version

click on line to add new node for line strings and polygons

Add button for feature delete

Is this necessary in addition to the keyboard shortcut?

Cannot draw more than one Polygon