Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rckbrcls/urbanus

Urban infrastructure analysis platform for extracting streets, enriching elevation, processing graphs, and editing projects.
https://github.com/rckbrcls/urbanus

civil-engineering fastapi geospatial gis maplibre nextjs postgis python sanitation sewer-network typescript urban-planning

Last synced: 1 day ago
JSON representation

Urban infrastructure analysis platform for extracting streets, enriching elevation, processing graphs, and editing projects.

Awesome Lists containing this project

README 

          
# URBANUS



> Open-source academic research prototype for preliminary sanitary sewer planning in low-income urban areas.



## Summary



URBANUS is a web-based decision-support platform developed in the context of academic research at the Institute of Mathematics and Computer Science of the University of Sao Paulo (ICMC-USP). The project supports the preliminary design of sanitary sewer collection networks by combining public geospatial data, graph modeling, topographic enrichment, interactive expert editing, and graph-routing algorithms.



The system is designed for the early planning stage of sanitation infrastructure projects. It helps engineers and technical teams screen public data, generate candidate layouts, inspect graph structures, and document preliminary alternatives before detailed engineering design, field surveys, and hydraulic validation.



This repository contains the implementation associated with the paper **"Supporting sanitation infrastructure planning in low-income areas with URBANUS"**. The current codebase is organized as a polyglot monorepo with a Next.js web application, a FastAPI/PostGIS backend, shared TypeScript packages, and a shared Python geospatial package.



## Paper Context



The paper frames URBANUS as a response to the technical and financial barriers that limit sanitation planning in underserved communities. In Brazil, sanitation deficits remain concentrated in peripheral and informal settlements, where municipalities and engineering teams often lack affordable computational support for early network planning.



URBANUS follows the Front-End Loading (FEL) methodology by targeting the first planning stage. The platform does not replace executive engineering design, survey-grade topographic data, or independent hydraulic validation. Its role is to support candidate generation and specialist inspection using public geospatial data and reproducible computational workflows.



The main contributions documented in the paper are:



- a graph-based pipeline for generating candidate sewage collector layouts from OpenStreetMap data and digital elevation models;

- an interactive web interface for expert inspection and refinement before processing;

- a real case study that quantifies the reduction in data-entry and processing effort for preliminary layout generation;

- a research path for automatic building detection from satellite imagery to improve sewage contribution estimates.



## Research Motivation



Planning a sewage collection network requires analyzing the street network, modeling flow according to terrain elevation, estimating sewage contribution per lot, defining feasible collector paths, positioning inspection structures, and validating technical constraints. These tasks are usually handled with specialized tools and manual spreadsheets, which can be expensive, slow, and difficult to access in low-income urban contexts.



URBANUS models the urban street network as a graph. Vertices represent intersections, dead ends, curves, intermediate points, collection points, and relevant topographic points. Edges represent street or collector segments and carry attributes such as geometry, length, road type, and elevation. After topographic analysis, the resulting collector network is represented as a directed graph aligned with gravity-driven flow constraints.



## Method Overview



The URBANUS method is organized around three main stages.



1. Data preparation: the user selects an urban area on the map, the system obtains street geometry from OpenStreetMap through the Overpass API, and the backend enriches graph vertices with elevation data from OpenTopography.

2. Expert graph editing: the user inspects the generated graph, edits nodes and connections, and makes domain-driven corrections before processing. The edited graph becomes the source of truth for the backend pipeline.

3. Sewer-network processing: the backend reconstructs the graph with NetworkX, identifies mandatory nodes, handles direction changes, simplifies redundant structures, detects elevation extrema and grade breaks, selects collection points, runs gravitational routing, repairs missing coverage, avoids invalid cycles, reduces nodes, and assigns inspection accessories.



Gravitational routing uses the Repeated Shortest Path Heuristic (RSPH), which connects mandatory nodes and collection points to an outlet or local collectors through successive least-cost path searches while favoring trunk reuse.



## Current Workflow



1. Create or open a project in the web interface.

2. Select an area on the map.

3. Fetch street geometry from OpenStreetMap through the Overpass API.

4. Enrich street vertices with elevation data from OpenTopography.

5. Inspect and edit the resulting graph.

6. Run the sewer-network processing pipeline.

7. Review flow direction, collection points, elevations, processed nodes, and processed edges.

8. Save and reload the processed sewer-network snapshot with the project.



## Main Features



- Project creation, listing, loading, deletion, and processed network persistence.

- Map-based bounding-box selection with area validation.

- Street import through a Next.js API route that queries Overpass API.

- Elevation enrichment through the FastAPI backend and OpenTopography.

- Interactive graph editing with node selection, movement, creation, connection, splitting, removal, undo, and redo.

- Sewer processing from the edited graph as the source of truth.

- RSPH routing for gravitational sewer-network layout generation.

- Graph sanitization, direction-change handling, elevation extrema detection, coverage repair, cycle prevention, node reduction, and accessory assignment.

- PostGIS persistence for projects, selected areas, graph geometries, and processed sewer-network data.

- Shared TypeScript and Python geospatial packages with parity tests for aligned domain behavior.



## Experimental Validation



The paper reports functional validation of the implemented web workflow and a case study in Barreiro do Rio Verde, in the municipality of Verdelandia, Minas Gerais, Brazil. The city was selected because of its low Human Development Index and irregular terrain, both representative of the target context for URBANUS.



The case study covered 21 street alignments from a total of 242 alignments in the municipality. A domain expert performed manual network planning with the same input data used by URBANUS, including preprocessing, profile generation, manhole placement, flow-direction analysis, spreadsheet-based hydraulic checks, and correction rounds.



For the 21 tested alignments, the manual process was estimated at about two weeks of working days. Extrapolated to the full set of 242 municipal alignments, the expert estimated about six months of work under normal working conditions. For the same 242 alignments, the total data-entry and processing time in URBANUS was less than one minute.



The paper also reports geometric accuracy for two algorithmic steps evaluated against the expert solution:



- 100% precision for enforcing the minimum 100 m spacing between inspection manholes;

- 89.5% precision for clustering nearby nodes into representative corner nodes.



These results are preliminary evidence for early-stage planning. They indicate that URBANUS can produce geometrically coherent layouts suitable for specialist refinement, but they do not remove the need for final engineering review, local surveys, or hydraulic validation.



## Research Module: Building Detection



The paper also documents a building-detection research module intended to improve sewage contribution estimates from satellite imagery. The module uses semantic segmentation to estimate built area, which can later feed sewage contribution calculations in the URBANUS backend.



Two pre-trained models were evaluated with fine-tuning on the Massachusetts Buildings Dataset: SAM, a general-purpose segmentation model based on Transformers, and DeepLab V3, a CNN-based segmentation model. After fine-tuning, SAM improved from 0.160 to 0.586 mean IoU, while DeepLab V3 improved from 0.177 to 0.600 mean IoU and reached 0.747 mean Dice.



This module was not validated in the Verdelandia case study. In that case, building-lot entries were provided manually by the specialist. Tighter integration between building detection and the sewer-routing workflow remains part of the research roadmap.



## Screenshots



Representative interface captures are available under `images/`.



![Project creation screen](images/starting-project.png)



![Area selection over the map](images/bounding-box-draw.png)



![Processed sewer-network view](images/small-case-after-processing.png)



## Tech Stack



- **Frontend:** Next.js App Router, React 19, TypeScript, MapLibre GL, `react-map-gl`, TanStack Query, Zustand, Radix/Base UI primitives, Tailwind CSS.

- **Backend:** FastAPI, Pydantic 2, SQLAlchemy async, asyncpg, GeoAlchemy, PostGIS, NetworkX, Shapely, Rasterio, NumPy, httpx.

- **Shared TypeScript packages:** pnpm workspaces, Turborepo, Vitest, `@urbanus/geo`, `@urbanus/constants`, `@urbanus/utils`.

- **Shared Python package:** uv workspace, Hatchling, pytest, `urbanus-geo`.

- **Infrastructure:** Docker Compose with `postgis/postgis:16-3.4`.



## Repository Structure



```text

URBANUS/

+-- apps/

|   +-- api/          # FastAPI service, SQLAlchemy models, geospatial persistence, graph pipeline

|   +-- web/          # Next.js app, map editor, project pages, API proxy routes

+-- packages/

|   +-- constants/    # Shared TypeScript constants

|   +-- geo/          # Shared TypeScript geospatial types and calculations

|   +-- utils/        # Shared retry, throttle, and rate-limit helpers

+-- py/

|   +-- urbanus-geo/  # Shared Python geospatial types and calculations

+-- images/           # Interface and experiment screenshots

+-- docker-compose.yml

+-- pnpm-workspace.yaml

+-- pyproject.toml

+-- turbo.json

```



## Architecture



The frontend owns the interactive workflow: project pages, map selection, street import, graph editing, visualization layers, result panels, and API proxy routes. The backend owns persistence, elevation enrichment, node extraction, and sewer-network processing. PostgreSQL/PostGIS stores project metadata, selected areas, street geometry, graph nodes, graph edges, and processed sewer-network snapshots.



Shared TypeScript and Python packages keep common domain concepts aligned without forcing a single implementation across ecosystems. TypeScript supports the web application, while Python supports the backend processing pipeline.



Important areas:



- `apps/web/app`: App Router pages and API routes.

- `apps/web/features/map`: map services, hooks, validators, constants, and graph-editing helpers.

- `apps/web/stores`: local state for projects, map state, area selection, graph editing, and pipeline results.

- `apps/api/src/urbanus_api/main.py`: FastAPI routes and processing orchestration.

- `apps/api/src/urbanus_api/data`: SQLAlchemy engine, tables, repositories, and PostGIS persistence.

- `apps/api/src/urbanus_api/core`: graph classification, sanitization, coverage repair, elevation extrema, routing, and optimization modules.



## Data Flow



1. The browser sends the selected bounding box to the Next.js `/api/streets` route.

2. The route queries Overpass API, clips the response to the selected area, and returns GeoJSON.

3. The web app sends street geometry to the elevation route, which proxies the request to FastAPI.

4. FastAPI fetches a GeoTIFF from OpenTopography and samples elevation at street vertices.

5. The frontend builds and edits the graph from the enriched street geometry.

6. The edited graph is sent to `POST /projects/{project_id}/process`.

7. FastAPI rebuilds the graph with NetworkX, applies the sewer pipeline, and returns a serialized sewer network.

8. The project and processed network are persisted in PostgreSQL/PostGIS and can be reloaded later.



## API Overview



Important FastAPI routes:



- `POST /projects`

- `GET /projects`

- `GET /projects/{project_id}`

- `DELETE /projects/{project_id}`

- `POST /nodes/extract`

- `POST /projects/{project_id}/process`

- `POST /elevation/enrich`



Important Next.js routes:



- `/`

- `/map`

- `/projects`

- `/projects/[id]`

- `/api/projects`

- `/api/projects/[id]`

- `/api/projects/[id]/process`

- `/api/streets`

- `/api/elevation/enrich`



## Requirements



- Node.js compatible with the checked-in Next.js and React versions.

- pnpm, as declared by `packageManager` in `package.json`.

- uv for the Python workspace.

- PostgreSQL/PostGIS, either local or through Docker Compose.

- Docker and Docker Compose for the included local infrastructure stack.



## Installation



Install JavaScript and Python dependencies from the repository root:



```bash

pnpm install

uv sync

```



The Python API declares `urbanus-geo` as a workspace source in `apps/api/pyproject.toml`, so root-level installation keeps the local Python packages aligned.



## Environment Variables



- `DATABASE_URL`: async SQLAlchemy URL for PostGIS. The local default in code is `postgresql+asyncpg://urbanus:urbanus@localhost:5432/urbanus`.

- `OPENTOPOGRAPHY_API_KEY`: key used by OpenTopography elevation enrichment.

- `PYTHON_API_URL`: backend URL used by the Next.js API layer. Docker Compose sets it to `http://server:8000`; local code defaults to `http://localhost:8000`.



## Running Locally



Root-level scripts:



```bash

pnpm dev

pnpm dev:web

pnpm dev:api

```



Makefile orchestration:



```bash

make install

make dev

make dev-web

make dev-api

```



Docker Compose stack:



```bash

docker compose up

```



## Validation



Documented checks:



```bash

pnpm lint

pnpm type-check

pnpm test

```



The TypeScript workspace uses Vitest. The Python API and Python geospatial package use pytest. Package-level READMEs document additional local checks when working inside a specific package.



## Current Status



The current implementation provides the functional basis of the URBANUS web version: project persistence, street import, elevation enrichment, graph editing, processing from the edited graph, processed-network visualization, PostGIS persistence, and automated tests for central geospatial and graph-processing components.



The main remaining research work is broader experimental validation across different urban areas, refinement of quality metrics, tighter integration between sewer routing and building detection, automatic sewage contribution estimates from detected buildings, and assessment of generalization under different urban morphologies and public-data quality conditions.