# amsterdam-ai-team/geolocalization_of_street_objects architecture

> Architecture diagram of the GitHub repository amsterdam-ai-team/geolocalization_of_street_objects, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amsterdam-ai-team/geolocalization_of_street_objects
- Repository: https://github.com/amsterdam-ai-team/geolocalization_of_street_objects

## Overview

##### Project Type and Purpose
- This is a data-processing pipeline/project combining a deep-learning object-detection stage (Faster R-CNN) with a geospatial triangulation stage (MRF-based).
- Purpose: automatically detect stationary objects (bicycle symbols) in Street-View-style panoramic images and estimate their real-world coordinates.

##### Top-Level Components
A. Data Ingestion & Storage
– “data/” folder: raw CSV detections, raw panoramas (downloaded via Street-View API)
– “output/” folder: final geolocated CSVs
B. Object Detection
– models/test.py: Python code fine-tuning + running Faster R-CNN
– scripts/YOLO_to_COCO_converter.py: format conversion
C. Postprocessing
– scripts/postprocessing.py: enriches raw detection output with camera RD-coords, viewpoint angles, depths
D. Geolocation Engine
– main.py: orchestrates the MRF triangulation procedure
– src/geometry.py: implements MRF solver, intersection math
– src/api_request.py: retrieves metadata (e.g. panorama positions) from external API
E. Visualization Examples
– examples/visualize_viewpoints.py, visualize_intersections.py

##### Data-Flow & Interactions
1. (Optional) Panoramic images & metadata ←→ External Street-View API (via src/api_request.py)
2. Raw images → models/test.py (Faster R-CNN) → raw detection CSV (data/faster_r-cnn_output/)
3. raw CSV → scripts/postprocessing.py → enriched CSV (data/postprocessing_output/)
4. enriched CSV → main.py → MRF triangulation (uses src/geometry.py) → output CSV in output/
5. output CSV → examples/visualize_*.py → visual plots

##### Architectural Patterns & Design Principles
- Pipeline / Batch Processing: clear sequential stages, each persisting intermediate results to disk
- Modularity / Separation of Concerns: detection, postprocessing, triangulation, visualization all live in distinct folders/modules
- Reusability / Extensibility:
– scripts folder holds converters and helper transforms
– src folder holds utility libraries (geometry, API wrappers)
- Data-Driven: all inputs/outputs are CSVs, making it easy to swap detection or triangulation stages

##### Important Technologies & Dependencies
- Python 3.x
- PyTorch + TorchVision (Faster R-CNN)
- NumPy, Pandas
- Shapely or custom geometry code for MRF intersections
- External HTTP requests (requests or similar for api_request.py)
- Visualization: Matplotlib, possibly GeoPandas (used in examples)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Ingestion & Storage
    subgraph "Data Ingestion & Storage"
        direction TB
        data_raw["data/ (raw panoramas & CSVs)"]:::storage
        data_frcnn["data/faster_r-cnn_output/bicycle_symbols_example.csv"]:::storage
        data_post["data/postprocessing_output/bicycle_symbols_example.csv"]:::storage
        output_folder["output/"]:::storage
        output_RD["output/bicycle_symbol_locations_2019_RD.csv"]:::storage
        output_latlng["output/bicycle_symbol_locations_2019_latlng.csv"]:::storage
        output_example["output/bicycle_symbols_example.csv"]:::storage
    end

    %% Object Detection
    subgraph "Object Detection"
        direction TB
        test_py["models/test.py\n(Faster R-CNN)"]:::compute
        yolo_cnv["scripts/YOLO_to_COCO_converter.py"]:::compute
    end

    %% Postprocessing
    subgraph "Postprocessing"
        direction TB
        post_py["scripts/postprocessing.py\n(enrich detections)"]:::compute
    end

    %% Geolocation Engine
    subgraph "Geolocation Engine"
        direction TB
        main_py["main.py\n(MRF triangulation)"]:::compute
        geom_py["src/geometry.py\n(MRF solver)"]:::compute
        api_py["src/api_request.py\n(API metadata)"]:::compute
    end

    %% External API
    SVAPI["Street-View API"]:::external

    %% Visualization
    subgraph "Visualization Examples"
        direction TB
        viz_vp["examples/visualize_viewpoints.py"]:::viz
        viz_int["examples/visualize_intersections.py"]:::viz
    end

    %% Data Flow
    SVAPI -.->|images & metadata| data_raw
    data_raw -->|images| test_py
    yolo_cnv -->|converted COCO| test_py
    test_py -->|CSV| data_frcnn
    data_frcnn -->|CSV| post_py
    post_py -->|CSV| data_post
    data_post -->|CSV| main_py
    api_py -.->|HTTP requests| SVAPI
    main_py -->|CSV| output_RD
    main_py -->|CSV| output_latlng
    main_py -->|CSV| output_example
    output_folder --> output_RD
    output_folder --> output_latlng
    output_folder --> output_example
    output_example --> viz_vp
    output_example --> viz_int

    %% Click Events
    click data_raw "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/tree/master/data/"
    click data_frcnn "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/data/faster_r-cnn_output/bicycle_symbols_example.csv"
    click data_post "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/data/postprocessing_output/bicycle_symbols_example.csv"
    click output_folder "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/tree/master/output/"
    click output_RD "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/output/bicycle_symbol_locations_2019_RD.csv"
    click output_latlng "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/output/bicycle_symbol_locations_2019_latlng.csv"
    click output_example "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/output/bicycle_symbols_example.csv"
    click test_py "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/models/test.py"
    click yolo_cnv "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/scripts/YOLO_to_COCO_converter.py"
    click post_py "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/scripts/postprocessing.py"
    click main_py "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/main.py"
    click geom_py "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/src/geometry.py"
    click api_py "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/src/api_request.py"
    click viz_vp "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/examples/visualize_viewpoints.py"
    click viz_int "https://github.com/amsterdam-ai-team/geolocalization_of_street_objects/blob/master/examples/visualize_intersections.py"

    %% Styles
    classDef storage fill:#bbdefb,stroke:#1e88e5,color:#1e88e5;
    classDef compute fill:#c8e6c9,stroke:#43a047,color:#256029;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#bf360c,stroke-dasharray: 5 5;
    classDef viz fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
```
