Skip to content

Latest commit

 

History

History
53 lines (39 loc) · 4.47 KB

README.md

File metadata and controls

53 lines (39 loc) · 4.47 KB
Raw

maplibre-gl-vector-text-protocol

Supports geospatial text based vector data using MapLibre GL JS in v1.15.0 or later.

It makes use of the addProtocol functionality that was added in version 1.15.0.

It can be used with Mapbox GL JS 1.x.x using the mapbox-gl-custom-protocol library. I haven't tested it with Mapbox GL JS 2+.

Web workers are used to convert CSV, TSV, Topojson, and OSM formats. KML, GPX, and TCX formats are based on XML and use the DOMParser, which isn't available to web workers, so they are converted to GeoJSON in the main thread.

Supported Formats 🗎

  • Topojson - A more compact JSON based format than GeoJSON that takes advantage of shared topologies.
  • OSM - Open Street Map json/xml.
  • KML - Keyhole Markup Language, popularized by Google Earth.
  • GPX - GPS Exchange Format - A common XML-based format used by may GPS devices.
  • TCX - Training Center XML - An XML-based format used by various Garmin devices and applications (e.g. Garmin Connect).
  • CSV - Comma-Separated Values, the old reliable of data formats. No options are exposed, Latitude fields must start with "lat" and Longitude fields must start with "lon" or "lng". Will also work with bar (|) and tab (\t) separated values.
  • TSV - Tab-Separated Value - Same as CSV, but it forces the delimiter to be a tab character (\t).

Objective ✨

The addProtocol feature makes it extremely easy to extend the existing functionality of MapLibre sources without creating a new source type using the addSourceType feature. This makes it very easy to support all kinds of new things in MapLibre.

Inspiration 💡

I have worked on many projects where users want to add their own data to a map, but their data is rarely in the right format. This library makes it as easy as adding a csv:// before the file path to bring a csv file in.

There are a lot of Geospatial File Formats out there, this library is intended to serve the most common formats (CSV, KML, GPX, Topojson, OSM) without creating a huge library. There are other formats I would like to support, but they will be available in different libraries.

External Libraries 📚

This project would not be possible if it weren't for the core libraries that drive it:

  • @tmcw/togeojson - Supported by placemark.io - KML, GPX, TCX support
  • csv2geojson - Supported by Mapbox - CSV, TSV support
  • topojson-client - From Mike Bostock - Topojson support
  • osm2geojson-lite - From tibetty - osm2geojson-lite support

I'd also like to thank the Mapbox🚀 and MapLibre teams for creating such a great project that is easily extendable.

Usage 🛠️

<script src="https://loc8.us/maplibre-gl-vector-text-protocol/dist/maplibre-gl-vector-text-protocol.js"></script>

// Add all types
VectorTextProtocol.addProtocols(maplibregl);

// Individual protocols can be added as well
maplibregl.addProtocol('csv', VectorTextProtocol.VectorTextProtocol);
maplibregl.addProtocol('kml', VectorTextProtocol.VectorTextProtocol);

Examples ⚙️

Codepen