Onboarding repository polyline

mbalfour-amzn commented 1 month ago

Motivation

This is a follow-up to the MapLibre discussion on adding compressed polyline support into the core MapLibre library. The community feedback from that discussion was that support would be helpful, but that it should be introduced as a separate optional library.

Compressed polylines are a category of data formats for performing lossy compression on coordinate data. Despite the name, the compression format is used to encode/decode both line strings and polygons. This compressed format is used as both input and output to various route and isoline APIs from a number of different location service providers: Google, Mapbox, HERE, Stadia Maps, OSRM, Valhalla, etc.

The compression formats used in the APIs are all based on Google’s Encoded Polyline Algorithm Format. Two of the three common variations are the mapbox/polyline library called with either 5 or 6 decimals of precision. The third variation is the heremaps/flexiblepolyline format, which improves upon the format by adding varying amounts of precision, better character encoding, and optional 3D support.

For users to display the compressed geometry in MapLibre, they need to use the correct library to decode the geometry, flip the lat/lng coordinates to lng/lat, and then embed them in the correct geometry in GeoJSON to then use as a MapLibre GeoJSON source.

This repository would contain a library that wraps the existing polyline formats in mapbox/polyline and heremaps/flexiblepolyline to make it easier to use these APIs in conjunction with MapLibre. The library would decode the geometry directly into GeoJSON that can be used as a MapLibre GeoJSON source.

The API would look like the following:

getCompressionAlgorithm() - gets the currently-selected compression algorithm for the library
setCompressionAlgorithm(CompressionAlgorithm) - sets the compression algorithm to use (library defaults to FlexiblePolyline)
encodeFromLngLatArray(Array<Array>, CompressionParameters) - encodes 2D/3D coordinates using the selected algorithm
decodeToLngLatArray(string) - decodes to 2D/3D coordinates
decodeToLineString(string) - decodes to GeoJSON LineString
decodeToPolygon(string) - decodes to GeoJSON Polygon
decodeToLineStringFeature(string) - decodes to GeoJSON Feature containing a LineString
decodeToPolygonFeature(string) - decodes to GeoJSON Feature containing a Polygon

Acceptance

[ ] Any two board members must agree to accept a new repository. Approved by: <@user1> <@user2>

Licensing

[ ] The repo license is BSD-3 or MIT. Repos may allow dual-licensing under other open source licenses, e.g. MIT OR Apache.
[ ] The repo contains Copyright (c) <year> MapLibre contributors in license file(s) and in the readme.

Special files

[ ] /README.md Description, link to the main maplibre.org page, name of the OSM-US Slack channel for discussions and an invite link, etc
[ ] /LICENSE Dual-licensed repos may have additional files like LICENSE-MIT and LICENSE-APACHE

[ ] /SECURITY_POLICY.txt Add the text:

For an up-to-date policy refer to
https://github.com/maplibre/maplibre/blob/main/SECURITY_POLICY.txt

[ ] /CONTRIBUTING.md
[ ] The repo has Pull Request and Issue Templates in /.github dir.
[ ] The repo has /.github/FUNDING.yml file copied from maplibre-gl-js/funding
[ ] /CODE_OF_CONDUCT.md This file should only link to our primary code of conduct. Use this markup for consistency: # Contributor Covenant [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/maplibre/maplibre/blob/main/CODE_OF_CONDUCT.md)

Repo Settings

General page

[ ] [Features] Disable unused features like wiki.
[ ] [Features] Enable Sponsorships checkbox (see also FUNDING.yaml above).
[ ] [Features] Enable Preserve this repository.
[ ] [Pull Requests] Community is encouraged to use squash merge. Disable other merge types if possible.
[ ] [Pull Requests] Enable Automatically delete head branches.

Access

[ ] The repo has at least one admin who is ideally not part of the Governing Board: <@user>

Branches

[ ] The primary branch is named main.
[ ] Set up branch rules to require CI pass and an approval before merge. For smaller projects it might be OK to ignore this rule.

Miscelaneous

[ ] The repo must not have any personal branches. All work should be done on forks and submitted via PRs, including by the admins.
[ ] Repo has a proper GitHub description and an optional web site Use the gear icon in the upper right corner of the repo page.
[ ] CI automatically runs on all pull requests before merging using GitHub actions
[ ] Grant admin rights to the board members and automation accounts for packages
- npmjs.com: package settings / invite: maplibreorg nyurik klokan lseelenbinder wipfli
- crates.io: package settings / add owner: nyurik klokan lseelenbinder wipfli

Community

[ ] The new repo has been announced in the #maplibre OSMUS slack channel.
[ ] The new repo has been announced in the next monthly meeting of the Technical Steering Committee.
[ ] The new repo has been announced in the @maplibre twitter.

HarelM commented 1 month ago

Is there a repo that needs to be maintained under the maplibre org as part of this onboarding request? If so, please update the post above.

mbalfour-amzn commented 1 month ago

I have the code locally, but I haven't submitted it to a repo yet since I didn't want to create a repo that was going to need to be deleted shortly afterwards. If that's a requirement for this process though, I can do that.

HarelM commented 1 month ago

yes, please publish it, and then we are transferring the repo if all goes well. Github will redirect the old repo to the new one, no need to delete anything.

maplibre / maplibre