Map to GeoJSON Converter

Web editor to convert raster maps to GeoJSON: upload an image, segment or draw regions, refine boundaries, georeference on a map and download a FeatureCollection.

---

Table of Contents

• Highlights
• Quick Start
• Usage
• Features
• Project Structure
• Local Startup
• Server Startup
• Test
• Contributing

---

Highlights

• 🆓 Free & Open-Source: No costs, ideal for students and researchers.
• Web Interface: Modern browser-based app with interactive georeferencing.
• 🎨 Assisted Extraction: Uses K-Means segmentation and edge detection for automatic polygon extraction.
• 🗺️ Multiple Inputs: Supports images (PNG, JPG, WebP) and SVG files.
• 📦 GeoJSON Export: Outputs standard GeoJSON FeatureCollection.

---

Quick Start

Prerequisites

• Python 3.8+ (Download)

Required Libraries

Library	Purpose
fastapi	Web framework for the app
uvicorn	ASGI server to run the app
opencv-python	Image processing & segmentation
numpy	Array operations
Pillow	Image loading
shapely	Polygon operations
pydantic	Data validation
python-multipart	File upload handling

One-Command (Linux/Mac)

# create venv, install deps and run local server
python3 -m venv .venv
.venv/bin/python -m pip install -r src/requirements.txt
./src/run_local.sh

Then open http://127.0.0.1:8000 in your browser. If the port is busy, run_local.sh will choose the next available port.

---

Local Startup

Use the local script to develop and test the app:

python3 -m venv .venv
.venv/bin/python -m pip install -r src/requirements.txt
./src/run_local.sh

---

Server Startup

start.sh is designed to expose the server using ngrok (optional):

python3 -m venv .venv
.venv/bin/python -m pip install -r src/requirements.txt
./start.sh

Useful environment variables:

PORT=8001 ./start.sh
NGROK_DOMAIN=cider-esquire-tinkling.ngrok-free.dev ./start.sh
NGROK_DOMAIN= ./start.sh          # use a random ngrok URL
START_NGROK=0 ./start.sh          # only FastAPI, no tunnel

A public tunnel requires ngrok installed and configured on the host.

---

Usage

1. Prepare your map image or SVG file.
2. Run the appropriate script (see Quick Start).
3. Choose calibration (preset or manual).
4. Export GeoJSON: FeatureCollection with polygons and points of interest.

For the detailed pipeline, see src/test con ai/pipeline.md.

---

Features

• Map image tracing: usa scansioni, disegni tecnici o mappe tematiche come base.
• Assisted segmentation: estrazione delle regioni colorate con tecniche di clustering.
• Manual editing: modifica vertici, duplica, elimina e rinomina aree.
• POI: aggiungi, trascina, rinomina ed esporta punti di interesse.
• Georeferenced export: esporta GeoJSON georeferenziato con i bounds impostati.
• Map image tracing: use scans, technical drawings, or thematic maps as a digitizing base.
• Assisted segmentation: extract colored regions using clustering techniques.
• Manual editing: edit vertices, duplicate, delete, and rename areas.
• POI: add, drag, rename, and export points of interest.
• Georeferenced export: export georeferenced GeoJSON using the set bounds.

---

Project Structure

The beta lives in src/:

• src/main.py: FastAPI entrypoint
• src/start.sh: server launcher with ngrok
• src/run_local.sh: local launcher
• src/static/: web UI
• src/routes/: API endpoints
• src/segmentation/: raster segmentation
• src/georeferencing/: coordinate conversion and alignment
• src/test_smoke.py: final smoke test

---

Test

.venv/bin/python -m pytest src/test_smoke.py -q

---

Contributing

Contributions welcome: open issues or PRs. Focus areas: improve segmentation, add input formats, enhance georeferencing.

---

References

• Visualize GeoJSON at https://geojson.io
• See docs/feasibility/ for feasibility studies and requirements.

---

© Map to GeoJSON Converter Project