How urban-toolkit/utk works
Project type and purpose
• This is a full-stack, cross-language visualization framework (“The Urban Toolkit” or UTK).
• It consists of:
a) A Python library (src/utk) for data loading, spatial computations, grammar parsing, map/network processing, and shadow/thematic calculations.
b) A Python-based HTTP server (src/utk_server.py) that wraps the core UTK library and exposes REST endpoints.
c) A TypeScript library (src/utk-ts) implementing the high-level grammar interpreter, data-API client, WebGL map/visualization pipeline, layer/shader management, and React helper components.
d) A React-based Single Page Application (src/utk-frontend) that ties everything together in the browser (with Jupyter and VR support).
File structure
• Top-level files: build scripts (build.sh), packaging (setup.py, requirements.txt), docs.
• Directories:
• docs/: user guides, API and grammar specifications, examples.
• src/utk/: Python package implementing data, grammar, and visualization core.
• src/utk_server.py: minimal Flask/FastAPI server exposing UTK functions.
• src/utk-ts/: TypeScript library packaged via Rollup for the browser.
• src/utk-frontend/: React app, Webpack/Gulp config, scripts, public assets, environment files, plus cave (Unity/VR) and Jupyter integrations.
README for additional insights
• The README emphasizes a “grammar-based framework for urban visual analytics,” support for 2D/3D maps, physical/thematic layers, data transformations, and OpenStreetMap integration.
Key components and their interactions
a. Presentation Layer (Browser / React SPA)
• Components: React pages (App.tsx, VR.tsx, Jupyter.tsx), UI widgets (GrammarPanel, MapRenderer, VisWidget, etc.), Jupyter bridge.
• Technology: React, TypeScript, Webpack, Babel, Gulp.
b. Visualization Engine (TypeScript Library)
• grammar-manager & grammar-interpreter: ingest high-level JSON grammar → produce visualization instructions.
• data-api & data-loader: fetch spatial/thematic data from Python server REST API or load from local files.
• mapview, layer-manager, shaders, WebGL context: assemble and render 2D/3D map layers (buildings, heatmaps, lines, points).
• Interaction channels & mouse events: handle user input.
c. Backend Application (Python Server)
• Exposes REST endpoints that wrap UTK’s core functions: data extraction (OSMnx, Osmium), building footprints, shadows, thematic layers.
• May use Flask or FastAPI (based on utk_server.py).
d. Core Data & Computation Library (Python UTK)
• Modules: data.py, map.py, osm.py, shadow_accumulator.py, urban_component.py, etc.
• Dependencies: Geopandas, OSMnx, Osmium, Shapely.
e. External Services / Data Sources
• OpenStreetMap servers, GeoJSON or other file inputs.
Architectural patterns and design principles
• Layered / Tiered Architecture:
1) Presentation (React SPA)
2) Application (TS library + Python server)
3) Data & Computation (Python UTK with spatial libs)
• Grammar-Based Design: High-level declarative grammar → interpreter pipeline.
• Modular, Pluggable Components: Separate packages for core library, server wrapper, TS engine, and SPA.
• Client-Server (RESTful) for dynamic data loading.
• WebGL rendering pipeline for high-performance visualization.