An interactive, educational tool for visualizing how different cartographic projections distort areas of the projected sphere. Built with WebGPU for real-time rendering in the browser.
Try it at: https://flatsphere.dev
Every flat map of the Earth introduces distortion. Flatsphere lets you explore that distortion hands-on by switching between projections, dragging the viewpoint, and building intuition with overlays like Tissot's indicatrices and graticule lines. The default visualization uses a world map texture for familiar geographic context, but you can load a local or remotely-hosted image, and even choose a source projection for it if it's not equirectangular by default.
The current view can be exported as PNG, JPEG, or WebP at custom dimensions or common presets (1080p, 4K, A4/Letter at 300 dpi, square). Exported images embed the projection state (destination projection, oblique view, rotation, zoom, pan, and overlay settings) as PNG tEXt, JPEG EXIF, or WebP XMP metadata. Using this metadata, the parameters used to produce a given image are recoverable from the file itself.
Projection math originally based on the flatsphere Go library, in turn based on the excellent Map Projections software suite by Justin Kunimune.
The site is served locally with Jekyll, which assembles index.html and the standalone pages (gallery, blog, merch, 404) from shared layouts and includes. Install the Ruby dependencies once, then run the dev server:
bundle install
make serveThis serves the whole site — including the app at / — on http://localhost:4000 with livereload. Open it in a browser with WebGPU support (recent Chrome/Edge, recent Safari, etc).
make serve also stages the projection data file into Jekyll's _data/ directory and watches it for changes. A plain static server (e.g. python3 -m http.server) will show an incomplete index.html with its Jekyll front matter and {% include %} tags unprocessed. The app's JavaScript, CSS, and WESL shaders are still loaded directly by the browser with no build step.
Requirements: Ruby 3.x and Bundler. The same Jekyll build runs in CI during deploys (see .github/workflows/static.yml).
The site is deployed to GitHub Pages via GitHub Actions. Deployments are triggered by pushing a version tag:
git tag v1.0.0
git push origin v1.0.0The tag name is injected into the page footer at build time and is expected to use a simple, HTML‑safe format (e.g., semantic versions like vX.Y.Z using only ASCII letters, digits, dots, and hyphens). Manual workflow_dispatch runs use dev as the version. Pushes to main without a tag do not trigger a deploy.
- Pico CSS — Minimal classless CSS framework
- Alpine.js — Lightweight reactive JavaScript framework
- WESL — WebGPU Extended Shading Language
- Jekyll — Static site generator for the standalone pages (blog, gallery, merch, 404)
World map texture sourced from Solar System Scope (free for non-commercial use).