city roads

The Problem

Rendering every road in a major city as a single visualization is a data problem: a city like Tokyo has over a million road segments, and fetching them from the OpenStreetMap Overpass API is slow and rate-limited. city-roads solves this by pre-indexing ~3,000 large cities into a compact protobuf cache, so the browser can load and render an entire city's road network without hammering the API.

What This Does

The app is a Vue 3 single-page application that fetches city boundary data, queries the Overpass API (or a cached protobuf index), and renders road segments as a WebGL scene. The core logic lives in src/lib/: createScene.js manages the WebGL rendering, Grid.js and GridLayer.js handle spatial tiling of road data, and findBoundaryByName.js resolves city names via Nominatim. The protobuf cache format is defined in src/proto/place.proto with matching encode.js/decode.js modules.

The UI layer in src/components/ provides the search box (FindPlace.vue), color picker, and editable labels. A scripting API is exposed for programmatic scene manipulation, documented in API.md. The repo also includes export utilities for SVG (svgExport.js) and protobuf (protobufExport.js) output.

How To Use It

Setup: The repo uses npm with Vite as the build tool (vite.config.js). Install dependencies and run the dev server:

npm install npm run dev

Configuration: There are no environment variables or API keys required. The app hits public OpenStreetMap endpoints (Overpass, Nominatim) directly. src/config.js holds tunable parameters like render limits and cache settings.

Running it: The entry point is src/main.js, which mounts the root App.vue component. The production build is npm run build, and deploy.sh handles publishing to GitHub Pages. No server-side component exists — everything runs client-side in the browser.

Real-World Use

A civic data journalist wants to produce a print-quality map of street density for a feature story. They load the app, search "Seattle", and export an SVG via the scripting API (svgExport.js). For programmatic use, the scene API in API.md lets a developer script custom camera paths or color schemes and render them to canvas, then save via saveFile.js. The protobuf export (protobufExport.js) allows the road data to be reused in other tools.

Code Health & Issues

Med - No tests detected - The entire src/ tree has zero test files. Core logic in src/lib/ (grid tiling, protobuf encode/decode) is untested and likely to break on edge cases like empty cities or malformed API responses. Med - No CI/CD pipeline - .github/ contains only FUNDING.yml; there is no workflow for automated build or test gating. deploy.sh is a manual script with no verification step. Low - Bundled third-party component - src/components/vue3-color/ is a vendored copy of a color picker library, including its own LICENSE. This inflates the repo and creates a maintenance burden if upstream fixes land. Low - babel.config.js present but Vite is used - Babel config is likely vestigial from an earlier Vue CLI setup; it's not referenced by vite.config.js and can be removed.

The codebase is otherwise clean: MIT license is present, .editorconfig and ESLint config enforce style, and the code is organized into focused modules with clear separation between rendering, data fetching, and UI.

The Bottom Line

This is a well-architected visualization tool with a thoughtful approach to a real data-fetching bottleneck. The lack of tests and CI makes it risky to extend, but for its intended use — a self-contained client-side city renderer — it's solid. Teams building on the scripting API should add their own test coverage before relying on it in production.