Strategy for maplibre-gl-js rendering enhancements

[ZeLonewolf]

Problem Statement

Project contributors cannot easily prototype and assess the performance of proposed enhancements to the maplibre-gl-js library. Additionally, it is difficult to create working public demonstrations of new proposed maplibre-gl-js enhancements to demonstrate their utility or assess their performance impact.

Desired End State

Project contributors can develop experimental functionality enhancements in maplibre-gl-js in an environment that doesn't impact end-users of maplibre-gl-js production releases. Using a live map, these experimental functions aim to be demonstrable in public-facing demos. By demonstrating new features with a working map that anyone on the web can use, we aim to demonstrate innovations in client rendering before submitting them as upstream changes. This strategy aims to position us as responsible maplibre contributors who show up with provers in hand, backed by hard performance metrics, for our upstream contributions. We wish the Americana project to be an incubator for cutting-edge capabilities, and this desire extends to our client rendering technology.

Background

The Americana project has been pushing the bounds of what's possible in digital vector maps. With big, flashy features like multilingual labels (#592) and name semi-colon processing (#666), as well as little features like our support for Kentucky Parkway shields (#119), the team has shown a knack for pushing the envelope with the tools that we have available. This aligns with our core values, specifically the one that says:

Challenge the status quo by showcasing innovation and invention

We've challenged the status quo several times and will continue to do so. Sometimes, the features we want to add require changes in the two technologies we depend on: OpenMapTiles on the back end; and maplibre-gl-js on the front end.

Until recently, the bulk of the changes we've needed have been on the OpenMapTiles side, and to that end, we've gotten 72 PRs merged as of today. I mention this because Americana has been a major driver of features in OpenMapTiles, and the two projects have grown in capability together. While we could have chosen to fork and customize OpenMapTiles for our purposes, we felt a responsibility as a general-purpose map style to contribute back. As of today, Americana remains 100% compatible with OpenMapTiles.

On the maplibre-gl-js side, we've merged just one key feature: maplibre/maplibre-gl-js#716, which allowed us to render upright highway shields, and with grateful thanks to @wipfli for getting it done. Because highway shields are the signature feature of our map, this seemingly minor change effectively launched us as a project. Americana was born!

As we've continued pushing the envelope, we find ourselves again looking to expand the maplibre-gl-js feature set to meet the growing desire on the project to do things nobody else has done before. In that vein, we've submitted several PRs and issues on the maplibre-gl-js github space that address some of the challenges we've encountered as our needs have grown:

• Implement replace-all expression maplibre/maplibre-gl-js#2059
• Add split and join expressions maplibre/maplibre-gl-js#2064
• Dynamic z-ordering across groups of style layers maplibre/maplibre-gl-js#2108

The maplibre team faces two challenges that stem from their adoption of the project from Mapbox. First, the platform is multi-platform, with native and web bindings for the style spec. Any features added to the gl-js library by rights should also be replicated on the native versions. However, Americana is currently only built for the web. While we would welcome someone implementing the shield generation library for native platforms, I'm unaware of anyone working on it. In addition, the upright highway shield functionality is only implemented on gl-js, so there's a bit of work to get this style running on native.

The second challenge is that the maplibre volunteer team has inherited a large, complex code base from Mapbox, a $100 million company with an extensive paid staff. That means any changes to maplibre-gl-js functionality add additional complexity and maintainability burdens to the volunteer teams. It's also clear that the library is used widely by a diverse group of users, including companies and hobbyists who all have a stake in the maplibre project's future direction.

In the discussions on these tickets, it's become clear that given these two constraints, the burden is on us as end-users to have a strong case for adding functionality for general use, and to prove that the functionality enhancements are necessary for general-purpose end-users rather than esoteric functionality by a community project.

Approach

To achieve the goals outlined here, I propose that we transition the project to use an experimental fork of maplibre-gl-js whenever we require experimental features not currently available in maplibre-gl-js. As this fork intends to host experimental features planned for contribution back to maplibre-gl-js, this fork will be considered temporary at all times. If we no longer require experimental features, the project will revert to the production maplibre-gl-js.

This fork of maplibre-gl-js is intended to host pre-PR features. It is NOT intended to compete with maplibre-gl-js. This fork will carry no guarantees, and other maplibre-gl-js users are discouraged from using this experimental fork in production code.

I propose that this experimental maplibre-gl-js be posted to npm, so it can integrate cleanly with our existing npm-based architecture and support developers. We'll give it an appropriate name label and description in npm, so it's clear that this is an experimental, non-production fork with appropriate caveats to that point.

I hope that staging our experimental features in a separate library will allow us to be more responsible contributors to the maplibre ecosystem and allow us to better innovate and support the vector rendering community by pushing the bounds of what's possible in a digital map.

[wipfli]

Thanks for sharing this, @ZeLonewolf. Improvements to MapLibre GL JS are welcome. If something should be too specific for GL JS, we can always think about a way to bring it in as a plugin. The more code we can share, the better.

Really cool that Americana chose MapLibre as its rendering engine. Happy to have you all in the community!