English / 日本語

mapbox-geo-circle-layer

Renders a simple circle on a Mapbox GL JS map.

Getting started

How to install

Please run the following command:

npm install https://github.com/codemonger-io/mapbox-geo-circle-layer.git#v0.2.0

Prerequisites

This library is intended to work with Mapbox GL JS v2.x and v3.x.

Usage

The following snippet adds a custom layer (id="example-circle") that renders a transparent blue circle with the radius of 100 meters around Tokyo Station:

import { GeoCircleLayer } from 'mapbox-geo-circle-layer';
// suppose map: mapbox-gl.Map
map.addLayer(new GeoCircleLayer('example-circle', {
    radiusInMeters: 100,
    center: { lng: 139.7671, lat: 35.6812 },
    fill: { red: 0.5, green: 0.5, blue: 1, alpha: 0.5 },
}));

You will see something like the following,

There is an example project in the example folder.

Updating properties

You can change the following properties of a GeoCircleLayer after creating it.

• radiusInMeters: radius in meters of the circle
• center: center of the circle
• fill: fill color of the circle
• numTriangles: number of triangles to approximate a circle

If you change any of the above properties, GeoCircleLayer triggers repaint of the map.

API documentation

Please refer to the api-docs/markdown folder.

Development

Prerequisites

Node.js version 14 or higher is required to build this library.

Installing dependencies

npm run install

Building the library

npm run build

Generating the API documentation

npm run build:doc

This also runs npm run build.

Running type check

You can run a type checker without building the library.

npm run type-check

Running tests

npm test

GitHub workflows

GitHub Actions that builds and verifies the target will start when a pull-request or push is initiated to the main branch.

Alternatives to this library

Built-in circle layer

Mapbox GL JS has a built-in circle layer. It can render multiple circles on a layer, but you have to specify radiuses in pixels (screen units). So it is not suitable for rendering a shape that circles a geographical area.

mapbox-gl-circle

mapbox-gl-circle offers more features than this library does. mapbox-gl-circle has an optional feature that enables interactive editing of circles. You might prefer this library for simplicity.

mapbox-gl-draw-circle

mapbox-gl-draw-circle also offers more features than this library does. mapbox-gl-draw-circle is actually implemented on top of mapbox-gl-circle. You might prefer this library for simplicity.