Projectr

Projectr is a highly experimental cross-platform map renderer with a focus on real-time projection of geographic vector data via GPU compute shaders.

Motivation

Web Mercator has been the de facto standard for web mapping for many years, despite its much-discussed weaknesses. Especially at a continental or global scale, the severe areal distortions at higher latitudes foster widespread misconceptions about the relative sizes of geographic features. While it does have cartographic strengths, its staying power is owed in part to the ease and efficiency with which it can be cut into and served as tiles.

The purely static maps of old made some compromises unavoidable. However, digital maps afford us a level of interactivity and adaptability that can be exploited for a better alternative. Adaptive Composite Map Projections by Bernhard Jenny, in particular, explored the idea of adaptively morphing between projections recommended by cartographic literature based on the map scale and central latitude of the viewport. Apart from difficulties in handling certain edge cases, it focuses mostly on solving cartographic challenges. While a WebGL demo exists, it only handles raster images. Most online map providers serve a vector tile view as the default.

Projectr aims to test and hopefully challenge the common sentiment that continuous reprojection of vector geometry is either not compatible with the idea of tiling and/or too computationally expensive to be done in real-time with current hardware. In particular, it aims to assess how maturing support for WebGPU—and thus compute shaders in the browser—may enable us to create such a web mapping system after all.

Overview

In its current form, the renderer is a work-in-progress port of d3-geo's spherical rotation, clipping, and projection pipeline to compute shaders. It is built on top of wgpu, vello, egui, and wesl-rs, and efficiently renders spherically-interpreted GeoJSON datasets (such as country borders, graticules, and custom polygons).

Key Features

• Real-Time Map Projections: Dynamically rotate and project geographic coordinate data on the GPU.
• Vector Geometry Rendering: High-quality rendering of GeoJSON features using vello in a layer-based system.
• Dynamic Clipping: On-the-fly clipping, with support for antimeridian and circle clipping boundaries.
• Interactive Viewer: An egui-based interface with support for zooming, rotating, and panning, changing clipping boundaries, and more.
• Feature Styling: A rudimentary but efficient system for dynamically styling geographic features based on zoom level, latitude/longitude, or custom logic.

For a complete list of supported projections with visual examples, please see the Projections Documentation.

Roadmap

The project is not, nor does it aim to become, production-grade software. It is meant to be a technical testbed for ideas on how to accelerate mapping operations using the GPU. With this in mind, these are broadly the current plans and priorities; more fine-grained tasks will be added to the issue tracker soon:

Robustness

• High-precision mode using an emulated double (float-float) polyfill.
• Replace the current spherical point-in-polygon test shader with a completely different approach; move it to the CPU if none provides the required precision and robustness. The current version is responsible for a large amount of visual artifacts, especially on higher-resolution data.

Performance

• Fast paths for data sizes that can be processed entirely by a single workgroup.
• Experiment with different parallelization schemes and vectorized writes in the geometry reconstruction stage of the clipping pipeline, which is currently the biggest bottleneck.
• Eliminate the need to read back dynamic allocation requirements from the GPU by 'freezing' buffer sizes after an initial warm-up period.
• Pipe our GPU-generated clipped and projected encoding directly into the Vello rendering pipeline without requiring a VRAM->RAM->VRAM roundtrip.
• Implement checkpointing for the "dynamic" memory allocation retry loop. Only re-run shader stages if necessary.

Memory Footprint

• Implement a bump buffer scheme, where multiple buffers are merged into one large buffer.
• Reuse buffers across shader stages more often.

Features

• PostClip support: Implement Cartesian clipping on the planar output of the projection pipeline. This will also allow us to support conic projections.
• Add Web support: The pipeline currently relies on device.poll(Wait), a blocking call that acts as a no-op on WebGPU, forcing a fallback to native APIs.
• Support for arbitrary spherical clipping boundaries (see d3-geo-polygon).
• Support for more file formats (e.g., Shapefile, TopoJSON), above all, vector tiles. As inspiration on how that might be achieved, see Automatic Projection Tiles by Jason Davies and also GeoJSON-VT.
• Bézier curve support, especially for adaptive projection curvature sampling.
• Line simplification (e.g., Ramer-Douglas-Peucker, Visvalingam–Whyatt, ...).
• Advanced CRS support (probably requires high-precision mode).

Code Structure and API

• Isolate and thus make it easier to replace shader stages with experimental versions.
• Make egui an optional dependency.
• Develop a GPU-friendly intermediate representation for geometric data that can be converted into a Vello scene encoding or other encodings efficiently.

Getting Started

Prerequisites

Ensure you have Rust and Cargo installed. Because this project relies heavily on wgpu and compute shaders, a Vulkan, Metal, or DX12 compatible GPU is required.

Building & Running

The examples are located at examples. To build and run them, use:

cargo run --bin custom_structs --release

The benchmark example (showing a flame graph for shader stages, a bar chart for the total frame-time, as well as other metrics) is supposed to be run with:

cargo run --bin benchmarking --release --features "wgpu-profiler"

WARNING: debug builds continuously write large debug traces, which severely degrades performance and may generally be undesired. The wgpu-profiler writes a few smaller files when a complete benchmark has concluded (must be started via the UI).

Acknowledgments

The project started by forking cartography-rs as a skeleton for rendering GeoJSON using Vello.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.