# alichaaban7/geoai-building-road-extraction architecture

> Architecture diagram of the GitHub repository alichaaban7/geoai-building-road-extraction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alichaaban7/geoai-building-road-extraction
- Repository: https://github.com/alichaaban7/geoai-building-road-extraction

## Overview

This repository is a two-approach GeoAI research application for extracting building footprints and road networks from remote-sensing imagery. Its principal workflow prepares labeled raster tiles and train/validation manifests, trains semantic or instance models, selects checkpoints and thresholds/post-processing on validation data, freezes final settings, then runs georeferenced inference and independent GIS evaluation. The Streamlit interface exposes experiment setup, stage execution, and result review. README documents optimization and ArcGIS Learn capabilities not fully represented by sampled source; their exact internal call paths are therefore omitted.

Main entry points: [`Roads/src/gis_inference.py`](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/gis_inference.py) (Georeferenced Inference), [`Roads/src/train.py`](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/train.py) (Road Training), [`Roads/src/inference.py`](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/inference.py) (Road Inference), [`ui/app.py`](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/app.py) (Streamlit Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Research UI"]
  node_interface["Streamlit Interface<br/>[app.py]"]
  node_building_ui["Buildings Page<br/>[buildings.py]"]
  node_road_ui["Roads Page<br/>[roads.py]"]
  node_result_reader["Result Reader<br/>[result_reader.py]"]
end

subgraph group_buildings["Building Extraction"]
  node_b_data["Building Data Prep<br/>[data.py]"]
  node_b_models["Building Models<br/>[factory.py]"]
  node_b_maskrcnn["Mask R-CNN Engine<br/>[trainer.py]"]
  node_b_sam["SAM-LoRA Training<br/>[trainer.py]"]
  node_b_infer["Building Inference<br/>[inference.py]"]
  node_b_instance_infer["Instance Inference"]
  node_b_optimize["Validation Optimization<br/>[optuna_search.py]"]
end

subgraph group_roads["Road Extraction"]
  node_r_data["Road Data &amp; Manifests<br/>[manifests.py]"]
  node_r_train["Road Training<br/>[train.py]"]
  node_r_models["Road Model Factory<br/>[factory.py]"]
  node_r_checkpoint["Checkpointing<br/>[checkpointing.py]"]
  node_r_optimization["Optuna Search<br/>[optuna_search.py]"]
  node_r_threshold["Threshold Search"]
  node_r_postsearch["Postprocess Search<br/>[search.py]"]
  node_r_infer["Road Inference<br/>[inference.py]"]
  node_r_gis["Georeferenced Inference<br/>[gis_inference.py]"]
  node_r_postprocess["Road Mask Processing<br/>[road_mask.py]"]
end

subgraph group_shared["Shared Evaluation"]
  node_r_eval["GIS Evaluation<br/>[gis_evaluation.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

node_researcher(("Researcher"))
node_arcgis[("ArcGIS / Raster Data")]
node_results[("Experiment Results")]

node_researcher -->|"uses"| node_interface
node_interface -->|"routes"| node_building_ui
node_interface -->|"routes"| node_road_ui
node_building_ui -->|"reads results"| node_result_reader
node_road_ui -->|"reads results"| node_result_reader
node_arcgis -.->|"imagery and labels"| node_b_data
node_b_data -.->|"training data"| node_b_models
node_b_models -->|"constructs model"| node_b_maskrcnn
node_b_maskrcnn -.->|"trained checkpoints"| node_b_infer
node_b_sam -.->|"trained checkpoints"| node_b_infer
node_b_infer -.->|"instance prediction"| node_b_instance_infer
node_b_optimize -.->|"tunes models"| node_b_models
node_road_ui -.->|"selects dataset"| node_r_data
node_r_data -->|"manifests"| node_r_train
node_r_train -->|"builds model"| node_r_models
node_r_train -->|"saves checkpoints"| node_r_checkpoint
node_r_optimization -->|"trains trials"| node_r_train
node_r_optimization -.->|"promotes winner"| node_r_checkpoint
node_r_threshold -->|"evaluates predictions"| node_r_infer
node_r_postsearch -->|"evaluates predictions"| node_r_infer
node_r_postsearch -->|"tests settings"| node_r_postprocess
node_r_checkpoint -->|"reconstructs checkpoint"| node_r_infer
node_r_infer -->|"runs raster inference"| node_r_gis
node_r_gis -->|"cleans mask"| node_r_postprocess
node_r_gis -.->|"writes GIS features"| node_arcgis
node_r_eval -.->|"computes scores"| node_metrics
node_r_gis -.->|"predictions for evaluation"| node_r_eval
node_r_eval -.->|"stores evaluation"| node_results
node_result_reader -->|"reads summaries"| node_results

click node_interface "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/app.py"
click node_building_ui "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/pages/buildings.py"
click node_road_ui "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/pages/roads.py"
click node_result_reader "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/utils/result_reader.py"
click node_b_data "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/maskrcnn/data.py"
click node_b_models "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/factory.py"
click node_b_maskrcnn "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/maskrcnn/trainer.py"
click node_b_sam "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/sam_lora/trainer.py"
click node_b_infer "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/inference.py"
click node_b_instance_infer "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/inference_instance.py"
click node_b_optimize "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/optional/optuna_search.py"
click node_r_data "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/data/manifests.py"
click node_r_train "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/train.py"
click node_r_models "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/models/factory.py"
click node_r_checkpoint "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/checkpointing.py"
click node_r_optimization "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/optional/optuna_search.py"
click node_r_threshold "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/optional/threshold_search.py"
click node_r_postsearch "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/postprocessing/search.py"
click node_r_infer "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/inference.py"
click node_r_gis "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/gis_inference.py"
click node_r_postprocess "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/postprocessing/road_mask.py"
click node_r_eval "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/evaluation/gis_evaluation.py"
click node_metrics "https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/evaluation/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interface,node_building_ui,node_road_ui,node_result_reader toneBlue
class node_b_data,node_b_models,node_b_maskrcnn,node_b_sam,node_b_infer,node_b_instance_infer,node_b_optimize,node_arcgis,node_results toneAmber
class node_r_data,node_r_train,node_r_models,node_r_checkpoint,node_r_optimization,node_r_threshold,node_r_postsearch,node_r_infer,node_r_gis,node_r_postprocess toneMint
class node_r_eval,node_metrics toneRose
class node_researcher toneIndigo
```

## Components

### Research UI

- [Streamlit Interface](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/app.py): `ui/app.py`
- [Buildings Page](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/pages/buildings.py): `ui/pages/buildings.py`
- [Roads Page](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/pages/roads.py): `ui/pages/roads.py`
- [Result Reader](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/ui/utils/result_reader.py): `ui/utils/result_reader.py`

### Building Extraction

- [Building Data Prep](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/maskrcnn/data.py): `Buildings/src/models/maskrcnn/data.py`
- [Building Models](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/factory.py): `Buildings/src/models/factory.py`
- [Mask R-CNN Engine](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/maskrcnn/trainer.py): `Buildings/src/models/maskrcnn/trainer.py`
- [SAM-LoRA Training](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/models/sam_lora/trainer.py): `Buildings/src/models/sam_lora/trainer.py`
- [Building Inference](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/inference.py): `Buildings/src/inference.py`
- [Instance Inference](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/inference_instance.py): `Buildings/src/inference_instance.py`
- [Validation Optimization](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Buildings/src/optional/optuna_search.py): `Buildings/src/optional/optuna_search.py`

### Road Extraction

- [Road Data & Manifests](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/data/manifests.py): `Roads/src/data/manifests.py`
- [Road Training](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/train.py): `Roads/src/train.py`
- [Road Model Factory](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/models/factory.py): `Roads/src/models/factory.py`
- [Checkpointing](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/checkpointing.py): `Roads/src/checkpointing.py`
- [Optuna Search](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/optional/optuna_search.py): `Roads/src/optional/optuna_search.py`
- [Threshold Search](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/optional/threshold_search.py): `Roads/src/optional/threshold_search.py`
- [Postprocess Search](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/postprocessing/search.py): `Roads/src/postprocessing/search.py`
- [Road Inference](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/inference.py): `Roads/src/inference.py`
- [Georeferenced Inference](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/gis_inference.py): `Roads/src/gis_inference.py`
- [Road Mask Processing](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/postprocessing/road_mask.py): `Roads/src/postprocessing/road_mask.py`

### Shared Evaluation

- [GIS Evaluation](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/evaluation/gis_evaluation.py): `Roads/src/evaluation/gis_evaluation.py`
- [Metrics](https://github.com/alichaaban7/geoai-building-road-extraction/blob/main/Roads/src/evaluation/metrics.py): `Roads/src/evaluation/metrics.py`

### Other components

- **Researcher**
- **ArcGIS / Raster Data**
- **Experiment Results**

## Connections

- Researcher → Streamlit Interface: uses (evidence: `ui/app.py`)
- Streamlit Interface → Buildings Page: routes (evidence: `ui/app.py`)
- Streamlit Interface → Roads Page: routes (evidence: `ui/app.py`)
- Buildings Page → Result Reader: reads results (evidence: `ui/pages/buildings.py`)
- Roads Page → Result Reader: reads results (evidence: `ui/pages/roads.py`)
- ArcGIS / Raster Data → Building Data Prep: imagery and labels
- Building Data Prep → Building Models: training data
- Building Models → Mask R-CNN Engine: constructs model
- Mask R-CNN Engine → Building Inference: trained checkpoints
- SAM-LoRA Training → Building Inference: trained checkpoints
- Building Inference → Instance Inference: instance prediction
- Validation Optimization → Building Models: tunes models
- Roads Page → Road Data & Manifests: selects dataset
- Road Data & Manifests → Road Training: manifests (evidence: `Roads/src/train.py`)
- Road Training → Road Model Factory: builds model (evidence: `Roads/src/train.py`)
- Road Training → Checkpointing: saves checkpoints (evidence: `Roads/src/train.py`)
- Optuna Search → Road Training: trains trials (evidence: `Roads/src/optional/optuna_search.py`)
- Optuna Search → Checkpointing: promotes winner (evidence: `Roads/src/optional/optuna_search.py`)
- Threshold Search → Road Inference: evaluates predictions (evidence: `Roads/src/optional/threshold_search.py`)
- Postprocess Search → Road Inference: evaluates predictions (evidence: `Roads/src/postprocessing/search.py`)
- Postprocess Search → Road Mask Processing: tests settings (evidence: `Roads/src/postprocessing/search.py`)
- Checkpointing → Road Inference: reconstructs checkpoint (evidence: `Roads/src/inference.py`)
- Road Inference → Georeferenced Inference: runs raster inference (evidence: `Roads/src/gis_inference.py`)
- Georeferenced Inference → Road Mask Processing: cleans mask (evidence: `Roads/src/gis_inference.py`)
- Georeferenced Inference → ArcGIS / Raster Data: writes GIS features
- GIS Evaluation → Metrics: computes scores
- Georeferenced Inference → GIS Evaluation: predictions for evaluation
- GIS Evaluation → Experiment Results: stores evaluation
- Result Reader → Experiment Results: reads summaries (evidence: `ui/utils/result_reader.py`)
