Spherical-Cap "Native Circle" for Mapbox GL JS


This project uses Turf.js to create a google.maps.Circle replacement, as a Mapbox GL JS compatible GeoJSON object.
Allowing the developer to define a circle using center coordinates and radius (in meters). And, optionally, enabling
interactive editing via draggable center/radius handles. Just like the Google original!

Getting Started

Include mapbox-gl-circle.min.js in
the of your HTML file to add the _MapboxCircle_ object to global scope:

``html

`

Or even better, fashionably importing it using a module bundler:

`npm
npm install --save mapbox-gl-circle
`

`javascript
const MapboxCircle = require('mapbox-gl-circle');
// or "import MapboxCircle from 'mapbox-gl-circle';"
`

Usage

$3

A google.maps.Circle replacement for Mapbox GL JS, rendering a "spherical cap" on top of the world.

Parameters

- center
- radius
- options

Examples

`javascript
var myCircle = new MapboxCircle({lat: 39.984, lng: -75.343}, 25000, {
editable: true,
minRadius: 1500,
fillColor: '#29AB87'
}).addTo(myMapboxGlMap);

myCircle.on('centerchanged', function (circleObj) {
console.log('New center:', circleObj.getCenter());
});
myCircle.once('radiuschanged', function (circleObj) {
console.log('New radius (once!):', circleObj.getRadius());
});
myCircle.on('click', function (mapMouseEvent) {
console.log('Click:', mapMouseEvent.point);
});
myCircle.on('contextmenu', function (mapMouseEvent) {
console.log('Right-click:', mapMouseEvent.lngLat);
});
`

#### constructor

Parameters

- center ({lat: number, lng: number} | \[number, number]) Circle center as an object or [lng, lat] coordinates
- radius number Meter radius
- options Object?
- options.editable boolean? Enable handles for changing center and radius (optional, default false)
- options.minRadius number? Minimum radius on user interaction (optional, default 10)
- options.maxRadius number? Maximum radius on user interaction (optional, default 1100000)
- options.strokeColor string? Stroke color (optional, default '#000000')
- options.strokeWeight number? Stroke weight (optional, default 0.5)
- options.strokeOpacity number? Stroke opacity (optional, default 0.75)
- options.fillColor string? Fill color (optional, default '#FB6A4A')
- options.fillOpacity number? Fill opacity (optional, default 0.25)
- options.refineStroke boolean? Adjust circle polygon precision based on radius and zoom
(i.e. prettier circles at the expense of performance) (optional, default false)
- options.properties Object? Property metadata for Mapbox GL JS circle object (optional, default {})

#### on

Subscribe to circle event.

Parameters

- event string Event name; click, contextmenu, centerchanged or radiuschanged
- fn Function Event handler, invoked with the target circle as first argument on
_'centerchanged'_ and _'radiuschanged'_, or a _MapMouseEvent_ on _'click'_ and _'contextmenu'_ events
- onlyOnce boolean? Remove handler after first call (optional, default false)

Returns MapboxCircle

#### once

Alias for registering event listener with _onlyOnce=true_, see #on.

Parameters

- event string Event name
- fn Function Event handler

Returns MapboxCircle

#### off

Unsubscribe to circle event.

Parameters

- event string Event name
- fn Function Handler to be removed

Returns MapboxCircle

#### addTo

Parameters

- map mapboxgl.Map Target map for adding and initializing circle Mapbox GL layers/data/listeners.
- before string? Layer ID to insert the circle layers before; explicitly pass null to
get the circle assets appended at the end of map-layers array (optional, default 'waterway-label')

Returns MapboxCircle

#### remove

Remove source data, layers and listeners from map.

Returns MapboxCircle

#### getCenter

Returns {lat: number, lng: number} Circle center position

#### setCenter

Parameters

- position {lat: number, lng: number}

Returns MapboxCircle

#### getRadius

Returns number Current radius, in meters

#### setRadius

Parameters

- newRadius number Meter radius

Returns MapboxCircle

#### getBounds

Returns {sw: {lat: number, lng: number}, ne: {lat: number, lng: number}} Southwestern/northeastern bounds

Development

$3

npm install

$3

npm start

$3

npm run browserify

$3

npm pack

$3

npm run docs

Changelog

$3

- optionalDependencies removed from package.json, making this package easier to depend on (#82)
- Bug fix for overlapping mouse-down events, causing the edit handle to lock until the user performs a full page refresh (#80)

$3

- New CI/CD integration, replacing Jenkins with GitHub Actions (#93)

$3

- Bug fix for layer switching in mapbox-gl>0.40.1 (#73)
- Half-fixed bug causing errors when adding circle to map style without the waterway-label layer

$3

- Performance improvements for Firefox and Edge on slow computers
(#64,
#59)
- Deprecated Docker build step

$3

- Transferring core project into SmithMicro organization, mblomdahl/mapbox-gl-circle -> smithmicro/mapbox-gl-circle

$3

- Handle center/radius drag interactions over Mapbox GL markers
- Watch for removal of map container and handle removal

$3

- Improved move animation (#55)

$3

- Add optional before argument to _MapboxCircle.addTo_
(#50)
- Updated center/radius handle interactions to make performance issues more subtle

$3

- Fix bug where the circle would always show a horizontal resize cursor on radius handles,
irrespective of position (top/bottom/right/left)

$3

- Bug fixes with respect to cursor style when hovering over editable-and-clickable circles
SPFAM-1293

$3

- Added support for passing minRadius and maxRadius options to _MapboxCircle_ constructor

$3

- Bug fix for handling _map.setStyle_ updates
- Added package version property to circle class

$3

- README updated with Getting Started section
- Improved usage examples
- Bug fixes:
- Creating circle instances with bundler import failed
- Docker build serving the wrong index.html

$3

- Performance and stability fixes

$3

- _MapboxCircle_ now supports subscribing to click and contextmenu (right-click) events

$3

- Added setters and getters for center/radius
- _MapboxCircle_ now allows subscribing to events and fires centerchanged/radiuschanged on user modification
- Improved API documentation + moved it into README / Usage

$3

- More bug fixes:
- The circle can now successfully remove itself from the map
- Multiple circles may be added to the map and edited without causing too much conflict
- Initial center/radius drag interaction no longer fails

$3

- Bug fixes; passing editable: false when creating a circle is now respected, along with any styling options

$3

- Publishing releases as @latest and pre-releases as @next to

- CI update for Docker image, now publishes releases and pre-releases to SMSI internal Docker registry,


$3

- CI updates, now integrates with GitHub and builds reliably (with unique version names) under


$3

- Added first-draft Jenkinsfile and started including package-lock.json
- Revised package.json scripts

$3

- Removed dead code and unused methods
- Restructured library, moving circle.js -> lib/main.js and index.js -> example/index.js
- Refactored helper functions from example/index.js` into _MapboxCircle_ class, obsoleted _index.html_ with
DOM updates in _example/index.js_
- Refactor into _MapboxCircle_ into new-style ES6 class
- Made _MapboxCircle.animate()_ and a bunch of properties private, added overridable defaults for
fillColor/fillOpacity
- Updated ESLint config to respect browser/commonjs built-ins and added docs to _MapboxCircle_ in order to
align with ESLint JSDoc requirements
- Updated project details in package.json and committed first-draft API documentation

$3

Updated circle from Mapbox bl.ocks.org sample.

Now provides handles for modifying position/radius. Seems to also do better performance wise.

$3

The initial 1.0.0 release is a modified version of
the Draw-Circle.zip archive we got from Mapbox.

Live demo of the original can be found here: