A robust, high-fidelity Urban Analytics ecosystem synthesizing modern Javascript 3D WebGL interfaces with high-performance locally accelerated Python Deep Learning models.
This platform evaluates structural walkability constraints and computational fluid aerodynamics natively across geographical layouts sourced dynamically from OpenStreetMap. Utilizing an isolated standalone backend matrix, it enables complete offline resilience without sacrificing computing capacity or polluting local operating environments.
We have designed this repository to be completely self-contained. It uses a portable Python package manager (uv), so you do not even need to have Python installed on your system!
To get the app fully running from scratch:
-
Clone the Repository
git clone https://github.com/aliksumin/Urban3DAnalysis.git cd Urban3DAnalysis -
Run the Automated Installer Double-click the
install.batfile in the root directory. This script will automatically:- Install all Node.js UI dependencies (
npm install). - Download a portable, isolated version of the
astral-uvPython package manager. - Provision a virtual isolated Python sandbox in the
backend/folder without touching your global registry. - Dynamically download the 208MB Microclimate AI Neural Network (
model.onnx) directly from HuggingFace to bypass GitHub file size limits.
- Install all Node.js UI dependencies (
-
Launch the Application Once installation is finished, double-click
run.bat. This automatically boots the PyTorch/FastAPI backend on Port 8000 and the Vite/React UI on Port 5173, instantly syncing them together and opening your browser.
To utilize the advanced semantic processing features of the Walkability module (which analyzes OpenStreetMap tags and infers building functions automatically), you need to provide a Google Gemini API Key.
- Obtain a free API key from Google AI Studio.
- Run the application and open the interactive 3D map.
- In the top-left menu bar, click Settings.
- Paste your API Key into the designated Gemini API Key field.
- You can toggle between
Gemini 2.5 Flash(for high-speed throughput) andGemini Provariants dynamically. Your key is stored securely in your browser's local state and is strictly used for client-side tag inference.
To massively supercharge the AI's understanding of urban layouts (especially in regions where OpenStreetMap data is poor), the app supports injecting proprietary Points of Interest (POI) data into the physical space before the AI processes it.
- Overture Maps Engine: Enabled automatically. This runs seamlessly in the background utilizing a specialized Python endpoint to parse global AWS S3 datasets. No API key is required.
- Google Places Context API: If you want hyper-accurate commercial zoning data:
- Navigate to the Google Cloud Console and create a project.
- Enable the Places API and generate an API Key.
- Inside the local application, open the Settings menu, enable the Google Places toggle, and paste your key.
- Amap (Gaode) Regional Overlay: If your mapped region falls within China, OpenStreetMap is often completely empty.
- Register at the Amap Open Platform (Gaode) and create a developer profile.
- Select Web Service API to generate your key.
- Paste it into the Amap section in the Settings menu. The app will automatically detect if your 3D boundary box is inside China and dynamically trigger this key for regional enrichment.
The software operates through two distinct, hyper-accurate simulation pipelines located on the right-hand panel of the interface.
The Walkability Engine calculates dynamic 15-minute city constraints using pathfinding Dijkstra mathematics dynamically tied to real-world pedestrian networks.
- Smart Routing: It detects roads and pedestrian pathways, converting them into navigable voxel nodes that snap directly to physical terrain heights rather than functioning as simple flat radii.
- AI-Powered Parameterization: You can deploy an AI Agent that connects to Gemini in the background. It will massively process up to 400 buildings simultaneously, analyzing native OSM metadata and tags to intelligently deduce exactly what function the building serves (e.g., Local Shop, Hotel, Clinic, School), replacing tedious manual data entry.
- Target Tracking HUD: Drops an agent into the 3D space, which maps surgical closest-target arcs out to various building and non-building amenities (like Parks and Plazas), verifying urban functional distribution.
A generative pipeline that outputs phenomenally accurate fluid dynamic tensors bypassing traditional CFD meshing bottlenecks.
- Hardware-Agnostic Neural Core: It runs entirely on ONNX CPU optimizations, taking in heightmaps and bounding box requests triggered by the 3D grid interface.
- High-Fidelity Voxel Visualization: When activated in the 3D environment, the backend computes velocity matrices and wake turbulence, projecting the results directly back into the 3D window natively via a colored, animated generative particle map.
- Dynamic Orientation: Adjust wind speed, gust ranges, and 360-degree source direction vectors inside the parameters panel to instantly witness aerodynamic shifts around city structures.
- React-Three-Fiber: Primary 3D simulation pipeline bridging WebGL via React hooks. Allows instantaneous matrix translation rendering InstancedMeshes and Geometry layers.
- Zustand: Decoupled, subscription-based logic manager enabling autonomous background AI chunking and application-wide persistence.
- Vite & TailwindCSS: Aggressive development bundler rendering a pristine Cyberpunk-inspired data environment.
- FastAPI & Uvicorn: A blazingly fast asynchronous endpoint wrapping the ONNX math predictions into standalone REST URLs easily traversable by front-end WebGL pulls.
- ONNXRuntime: Decodes and executes deep learning models cleanly with minimal RAM.
- astral-uv: The deployment package manager that sandboxes Python components, eliminating dependency hell.