CityPortraits

A comprehensive urban analysis framework that creates detailed city portraits through the integration of spatial, documentary, and data-driven methodologies. This project showcases architectural heritage and urban development patterns across Albanian cities.

🌟 Overview

CityPortraits bridges traditional architectural analysis with modern data science to reveal hidden patterns and relationships in urban systems. The framework combines:

• Contextual Analysis: Historical and narrative sources translated into structured knowledge
• Spatial Analysis: Geometric and relational structures derived from mapped data
• Data Analysis: Quantification and validation across multiple urban datasets

📊 Data Sources

Primary Datasets

• OpenStreetMap (OSM): Street networks, building footprints, POI data
• Global Human Settlement Layer (GHSL): Population density and built-up areas
• Global Data Explorer (GDE): Socio-economic indicators
• Albanian State Inspectorate of Geology (ASIG): Geological and environmental data
• Population Census: Demographic and socio-economic statistics

Derived Analysis

• Urban pattern recognition and classification
• Spatial relationship modeling
• Temporal evolution tracking
• Comparative urban metrics

🛠️ Technical Implementation

Framework Components

• MkDocs: Static site generation with Material theme
• JavaScript Libraries: Cytoscape (network graphs), Leaflet (maps), Mermaid (diagrams)
• Data Processing: JSON-based data structures for actors, events, and places
• Interactive Visualizations: Timeline maps, network graphs, and pattern displays

Project Structure

CityPortraits/
├── docs/
│   ├── index.md
│   ├── print_all.md
│   ├── about/
│   ├── assets/
│   │   ├── data/
│   │   ├── images/
│   │   └── outputs/
│   ├── case_studies/
│   │   ├── index.md
│   │   └── *.ipynb
│   ├── methodology/
│   │   ├── contextual_analysis/
│   │   ├── spatial_analysis/
│   │   └── data_analysis/
│   ├── model/
│   ├── javascripts/
│   └── stylesheets/
├── mkdocs.yml
└── README.md

🚀 Getting Started

Prerequisites

• Python 3.8+
• pip package manager

Installation

1. Clone the repository

   git clone https://github.com/greamarchitects/CityPortraits.git
   cd CityPortraits

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Serve locally

   mkdocs serve

5. Open in browser

   http://127.0.0.1:8000
   

Development

• Build for production: mkdocs build
• Deploy: mkdocs gh-deploy
• Add content: Edit Markdown files in docs/ directory
• Customize styling: Modify docs/stylesheets/extra.css

📈 Key Features

Interactive Components

• Timeline Maps: Historical event visualization with Leaflet
• Network Graphs: Actor-event-place relationships with Cytoscape
• Urban Patterns: GIF animations of morphological evolution
• Responsive Design: Mobile-friendly interface

Analytical Tools

• Multi-scale Analysis: From building to territorial levels
• Cross-temporal Comparison: Historical vs. contemporary patterns
• Data Validation: Statistical consistency checking
• Pattern Recognition: Automated urban morphology classification

Objectives

1. Urban System Reconstruction: Reconstruct comprehensive urban systems from fragmented data
2. Cross-contextual Comparison: Enable meaningful comparison across geographical contexts
3. Evidence-based Insights: Generate actionable insights for urban planning and heritage conservation

Contributing

We welcome contributions to improve the framework and expand the analysis to additional cities.

Ways to Contribute

• Add new case studies
• Improve data processing pipelines
• Enhance visualization components
• Expand methodological documentation
• Report bugs and suggest features
• Collaborate! : Contact

Development Guidelines

• Maintain data format consistency
• Document new features and methodologies

License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GREAM Architects: For providing the analytical framework and case study data
• Summer School DOCOMOMO: For the collaborative research environment
• Open Data Community: For providing accessible urban datasets
• Material for MkDocs: For the excellent documentation framework

Contact

GREAM Architects

• Website: greamarchitects.com
• Project: CityPortraits Urban Analysis Framework
• Date: April 2026

---

This framework represents a comprehensive approach to urban analysis, combining traditional architectural expertise with modern data science methodologies to create meaningful insights for urban planning and heritage conservation.