Mapbox-gl-path
Mapbox-gl-path allows you to create paths on a map with or without the help of various directions APIs.
It requires Mapbox-gl-js (or Maplibre-gl-js) as a dependency.
Quick start
Installation
Install Mapbox-gl-path with your package manager (npm is used in this example):
npm install @makina-corpus/mapbox-gl-pathUsage in your application
How to import dependencies
import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";
import MapboxPathControl from "@makina-corpus/mapbox-gl-path";
By using it in the <head> of your HTML file
<script src="https://api.mapbox.com/mapbox-gl-js/v2.2.0/mapbox-gl.js"></script>
<link
href="https://api.mapbox.com/mapbox-gl-js/v2.2.0/mapbox-gl.css"
rel="stylesheet"
/>
<script src="./dist/index.js"></script>Sample configuration
mapboxgl.accessToken = "YOUR_ACCESS_TOKEN";
const map = new mapboxgl.Map({
container: "map",
style: "mapbox://styles/mapbox/streets-v11",
center: [2.21, 46.22],
zoom: 5,
});
const mapboxPathControl = new MapboxPathControl(parameters);
map.addControl(mapboxPathControl);A working example is available at rollup.config.dev.js, look at development part.
To run it, you need to add a mapboxglToken environment variable to your .env file. See Run Locally section below.
API Reference
Parameters
All of the following parameters are optional.
{
directionsThemes: DirectionsTheme[] | undefined;
featureCollection: GeoJSON.FeatureCollection<GeoJSON.Geometry> | undefined;
layersCustomisation: LayersCustomisation | undefined;
lineString: GeoJSON.Feature<LineString> | undefined;
themeSelectionType: ThemeSelectionType | undefined;
translate: Function | undefined;
useRightClickToHandleActionPanel: boolean | undefined;
}
directionsThemes - DirectionsTheme[] | undefined
directionsThemes is an array listing all the themes for providing directions. Each directionTheme has its own parameters:
interface DirectionsTheme {
id: number;
name: string;
getPathByCoordinates: (
coordinates: number[][]
) => Promise<DirectionsThemeResponse | undefined>;
selected: boolean | undefined;
}The getPathByCoordinates function should return an object of type DirectionsThemeResponse with the coordinates between two points, waypoints and, if necessary, phantom junctions lines between waypoints and points.
If an element of the array has the prop selected set to true, it will be pre-selected. If there is more than one selected, the first one in the list will be selected.
interface DirectionsThemeResponse {
coordinates: number[][];
waypoints: Waypoints | undefined;
}
interface Waypoints {
departure: number[];
arrival: number[];
}
featureCollection - GeoJSON.FeatureCollection<GeoJSON.Geometry> | undefined
The featureCollection includes features that can be of type Point or Linestring.
A Linestring can be a line between points or a phantom junction line (the latter must have a isPhantomJunction properties equal to true).
layersCustomisation - LayersCustomisation | undefined
layersCustomisation parameter allows to define an infinite number of layers for each Point or Linestring in order to easily style them.
interface LayersCustomisation {
lineLayerList: LayerCustomisation[];
phantomJunctionLineLayerList: LayerCustomisation[];
pointLayerList: LayerCustomisation[];
}
interface LayerCustomisation {
id: string | undefined;
layout: AnyLayout;
paint: AnyPaint;
type: string | undefined;
}
lineString - GeoJSON.Feature | undefined
Like featureCollection parameter, it draws the lineString on the map.
If the lineString does not contains path and point properties to describe how to build a feature collection, automatic Points will be added:
- If the first and last point have the same coordinate, the lineString is considered to be looped so one point will be placed at that coordinate and two others will be placed at equal distance from each other.
- Otherwise, two points will be added to the edges.
If featureCollection parameter is set, this lineString parameter is ignored.
themeSelectionType - ThemeSelectionType | undefined
type ThemeSelectionType = "select" | "radioList";Determines the HTML element for theme selection. Default set to radioList.
translate - Function | undefined;
A function to provide locales. The default language is English (See src/i18n.js).
useRightClickToHandleActionPanel - boolean | undefined;
Boolean to use right or left mouse click to open the action panel. Default value is false (so left click).
Methods
clearFeatureCollection
Clears the paths from the map.
getFeatureCollection
Get the current FeatureCollection drawn.
Returns GeoJSON.FeatureCollection<GeoJSON.Geometry>
getLineString
Get the current drawn FeatureCollection and concatenates the collection as a LineString. The properties contain path and point elements that helps Mapbox-gl-path reconstruct the feature collection.
Returns Feature<LineString>
setFeatureCollection
Parameter: GeoJSON.FeatureCollection<GeoJSON.Geometry>
The featureCollection includes features that can be of type Point or Linestring.
A Linestring can be a line between points or a phantom junction line (the latter must have a isPhantomJunction properties equals to true).
setLineString
Parameter: GeoJSON.Feature<LineString>
It draws the lineString on the map.
If the lineString does not contains path and point properties to describe how to build a feature collection, automatic Points will be added :
- If the first and last point have the same coordinate, the lineString is considered to be looped so one point will be placed at that coordinate and two others will be placed at equal distance from each other.
- Otherwise, two points will be added to the edges.
setLoopTrail
It will draw the path between the last point and the first point only if point count is greater than 3.
setOneWayTrail
It will remove the path between the last point and the first point.
Events
Mapbox-gl-path fires a number of events. All of these events are namespaced with MapboxPathControl and are emitted from the Mapbox GL JS map object. All events are all triggered by user interaction.
map.on("MapboxPathControl.create", function (event) {
console.log(event.createdPoint);
});MapboxPathControl.create
Fired when a Point is created. The event data is an object with the following shape:
{
featureCollection: GeoJSON.FeatureCollection<GeoJSON.Geometry>,
createdPoint: Feature<Point>,
}MapboxPathControl.delete
Fired when a Point is deleted. The event data is an object with the following shape:
{
deletedPoint: Feature<Point>,
}MapboxPathControl.update
Fired when a Point is updated. The event data is an object with the following shape:
{
featureCollection: GeoJSON.FeatureCollection<GeoJSON.Geometry>,
}MapboxPathControl.loop
Fired when a Loop is activated. The event data is an object with the following shape:
{
featureCollection: GeoJSON.FeatureCollection<GeoJSON.Geometry>,
}MapboxPathControl.unLoop
Fired when a Loop is deactivated. The event data is an object with the following shape:
{
featureCollection: GeoJSON.FeatureCollection<GeoJSON.Geometry>,
}Run Locally
Clone the project
git clone git@github.com:makinacorpus/mapbox-gl-path.gitGo to the project directory
cd mapbox-gl-pathInstall dependencies
npm installStart the server
mapboxglToken="YOUR_ACCESS_TOKEN" npm run startBuild
npm run build