Quinx Worldmap Viewer

An open-source, five-point map projection explorer that changes how the world map is seen. It draws the map as a tiling square. You can zoom, rotate, and hover over countries to see their names. Download it and it runs fully offline, no internet needed.

Why this matters

Most maps distort the world to make it flat. Mercator stretches the poles until Greenland looks the size of Africa. Other projections tear the world in half just to keep one point undistorted. The Peirce quincuncial projection takes a different approach. It folds the whole sphere into one square, keeping angles and shapes accurate everywhere except four small points. Because of that, the map tiles perfectly. Pan far enough in any direction and the world just starts over, coastlines and all.

That's not just a neat trick. It makes it easy to see how landmasses relate across what would normally be a map's edge, and it turns the shape of the projection itself into something you can feel by dragging around, not just read about. That's what this viewer is for: drag it, rotate it, zoom in, toggle the graticule, and watch the world tile itself in real time instead of looking at a still image in a textbook.

Getting started

Use the Quinx Worldmap Viewer Online

Download Quinx Worldmap Viewer v0.1

This is a predownloaded, ready-to-run build: the D3 libraries and Natural Earth country data already ship inside assets/ and data/ — no setup script, no internet connection required. Just open index.html in a browser.

If you're working from source instead of this shipped build, see "Building from source" below.

Controls

• Drag to pan, scroll / pinch to zoom, hover / tap a country for its name.
• Reset view — returns to the default pan and zoom.
• ↺ / ↻ — rotate the map 90° counter-clockwise / clockwise.
• Graticule — toggles the lat/long grid overlay. On by default.
• Labels — toggles the in-map country labels. On by default.
• Dark theme / Light theme — switches between the ink-and-brass palette and a parchment palette; the choice is remembered and defaults to your system's light/dark setting on first visit.
• Fullscreen — expands the map to fill the screen (hidden if your browser doesn't support the Fullscreen API).
• Export PNG — saves the current pan/zoom/rotation as a PNG at full resolution.
• About (bottom-left) — opens the panel explaining the projection, with credit and a link to the source on GitHub.
• Keyboard: arrow keys pan, +/- zoom, [/] rotate.
• On narrow screens, the top-left controls collapse behind a menu button to keep the map uncluttered.

Folder layout

index.html                          the app
setup_assets.py                     re-downloads assets from source (optional, see below)
assets/
  d3.min.js                         D3 v7 (ISC license)
  d3-geo-projection.min.js          d3-geo-projection v4 (ISC license)
  authorship-placeholder.png        header image (placeholder — final art TBD)
data/
  ne_110m_admin_0_countries.js      coarse country data, loads first
  ne_50m_admin_0_countries.js       detailed country data, loads in behind it

Building from source

setup_assets.py is kept in the repo for anyone who wants to rebuild this folder from scratch (e.g. to pick up newer D3 or Natural Earth releases) rather than use the bundled copies. It needs an internet connection and is not required for the predownloaded build above:

python3 setup_assets.py

This re-downloads:

• assets/d3.min.js, assets/d3-geo-projection.min.js — the D3 libraries
• data/ne_110m_admin_0_countries.js, data/ne_50m_admin_0_countries.js — Natural Earth country boundaries (public domain), wrapped as local JS files

Possible future work

• Projection switcher (Peirce / Guyou oblique / Adams transverse). d3.geoPeirceQuincuncial() is quincuncial(guyouRaw).scale(111.48) under the hood, and that quincuncial() wrapper takes a .rotate([lambda, phi, gamma]) (default [-90, -90, 45]) that determines where the poles land on the square — so the other two arrangements described above are, in principle, just different rotation triples on the same construction, not new projection math. The app's calibrate() already discovers the tile lattice from whatever projection object it's handed (via bisection, not hardcoded pole positions), so it shouldn't need to change. What would need work: finding the exact rotation values for the historical Guyou and Adams aspects (trial and error, checking pole placement visually), and turning buildPaths() / the graticule / the hit-test color map — all currently built once at load — into something rebuildable on demand without a jarring flash. Rough estimate: a few focused hours, no new dependencies.

Why local files instead of a CDN

Browsers block fetch() of local files when a page is opened directly via file://, for security reasons. Rather than requiring a local web server just to view a map, index.html loads its data as plain <script> tags instead (which aren't restricted that way) — which is why the libraries and map data are shipped as local files rather than pulled from a CDN at runtime.

About the projection

The quincuncial projection was devised by Charles Sanders Peirce in 1879, while he was working for the U.S. Coast and Geodetic Survey. Peirce is better known today as a philosopher and logician — one of the founders of pragmatism — but cartography was part of his day job, and this projection was his attempt at a conformal map that could tile the plane without the usual polar distortion. He published it in the American Journal of Mathematics the same year.

A few decades later, two other cartographers worked out related arrangements of the same construction. The French engineer Émile Guyou (1887) produced an oblique version that rotates the layout so the poles sit at the midpoints of the square's edges rather than the center. In 1925, Oscar Sherman Adams, also at the U.S. Coast and Geodetic Survey, published a transverse version with the poles at the square's corners, as part of a broader survey of elliptic-function-based world maps, Elliptic Functions Applied to Conformal World Maps — the same publication most modern references, including this one, still cite for the underlying math.

Credits & acknowledgements

• D3.js and d3-geo-projection — ISC licensed, power the projection math and rendering.
• Natural Earth — public domain country boundary data.
• cspersonal/peirce-quincuncial-projection — reference implementation consulted during development.
• Built by The Black Temple.

Notes

• If you'd rather point at the CDN-hosted originals instead of local copies (e.g. for easier updates), edit the <script src="assets/..."> tags near the top of index.html and the loadScript('data/...') calls in the loadData() function.