repo: restore README after branch-only tool error

2026-08-26 21:35:56 +02:00
parent fd52142ef6
commit 82458b4d29
1 changed files with 267 additions and 1 deletions
@@ -1 +1,267 @@
-noop
+# GeoIntel
+
+GeoIntel ondersteunt een gesynchroniseerde tweeschermwerkruimte: de kaart blijft
+maximaal zichtbaar op het hoofdscherm terwijl analyses, kwaliteitsbewijs en
+resultaten live in een tweede venster staan. Zie
+[`docs/DUAL_DISPLAY_WORKFLOW.md`](docs/DUAL_DISPLAY_WORKFLOW.md).
+
+<p align="center">
+  <img src="frontend/public/geointel-icon-180.png" width="92" alt="GeoIntel logo">
+</p>
+
+<p align="center"><strong>Evidence-first GeoAI voor België en de Belgische Noordzee.</strong></p>
+
+GeoIntel is een kaartgerichte GeoAI-workbench waarin officiële databronnen,
+ruimtelijke analyse, PyTorch-computervisie, QA/QC en export samenkomen. Het
+platform bewaart niet alleen een resultaat, maar ook de bron, ruimtelijke
+context, modelversie en het bewijs waarmee dat resultaat gecontroleerd kan
+worden.
+
+De release ondersteunt heel België en de juridisch onderscheiden Belgische
+Noordzeezones. Regionale bronnen blijven herkenbaar: GRB, PICC, UrbIS en
+maritieme datasets worden niet voorgesteld alsof ze dezelfde semantiek,
+resolutie of actualiteit hebben.
+
+> **Data → ruimtelijke verwerking → AI-resultaat → kwaliteitsbewijs → export**
+
+![GeoIntel landingspagina](docs/assets/portfolio/geointel-landing-hero.png)
+
+## Waarom GeoIntel?
+
+Veel geoportalen tonen lagen. GeoIntel ondersteunt een volledige,
+controleerbare analyseketen:
+
+- selecteer een officiële grens of teken een eigen Area of Interest;
+- combineer vector-, raster- en historische bronnen met expliciete dekking;
+- voer GIS- en CUDA-versnelde beeldanalyse uit;
+- vergelijk kandidaatresultaten met referentiedata;
+- inspecteer false positives, false negatives, overlap en provenance;
+- exporteer alleen wat als reproduceerbaar resultaat is vastgelegd.
+
+Mol en de Kempen blijven de gouden regressiegebieden. De productgrens is heel
+België plus de juridisch benoemde Belgische maritieme zones.
+
+## Product in beeld
+
+De onderstaande screenshots zijn rechtstreeks vastgelegd op de actuele
+Unraid-productieomgeving. De gastmodus toont een beperkte, alleen-lezen
+demowerkruimte; operatorfuncties en nieuwe analyses blijven afgeschermd.
+
+### Interactieve projectketen
+
+De landingspagina vertaalt de technische keten naar vier interactieve
+schakels. De illustratie reageert op selectie, bronnen, analyse en bewijs en
+respecteert automatisch `prefers-reduced-motion`.
+
+![Interactieve GeoIntel-projectketen](docs/assets/portfolio/geointel-interactive-story.png)
+
+![Geanimeerde GeoIntel-projectketen](docs/assets/portfolio/geointel-interactive-project-chain.gif)
+
+### Kaart als werkruimte
+
+De kaart blijft het primaire werkblad. Thema, broncontext, selectie en
+resultaten zijn vanuit dezelfde ruimtelijke context bereikbaar.
+
+![GeoIntel kaartwerkruimte](docs/assets/portfolio/geointel-workbench-map.png)
+
+### Kwaliteit vóór resultaat
+
+QA/QC is een eerste-klas workflow. Bewaarde controles koppelen scores aan
+objectbewijs, kandidaat- en referentielagen en technische provenance.
+
+![GeoIntel kwaliteitscontrole](docs/assets/portfolio/geointel-workbench-quality.png)
+
+### Mobiele werkruimte
+
+Dezelfde kaartgerichte workflow blijft bruikbaar op een smal scherm. Thema's,
+selectieacties en de kaart worden gestapeld zonder de actieve werkcontext te
+verbergen.
+
+![GeoIntel mobiele werkruimte](docs/assets/portfolio/geointel-workbench-mobile.png)
+
+## Kernmogelijkheden
+
+| Domein | Mogelijkheden |
+| --- | --- |
+| Werkgebieden | Officiële grenzen, vrije AOI-selectie, clipping en buffering |
+| Bronnen | GeoJSON, vector, raster, orthofoto, historische en regionale catalogi |
+| GIS | CRS-normalisatie, spatial joins, rasterstatistiek, tile- en selectieanalyse |
+| GeoAI | PyTorch, Ultralytics YOLO en SAM-compatibele abstrahering |
+| Tijd | Immutable DatasetVersions en vergelijking van ruimtelijke snapshots |
+| QA/QC | Precision, recall, F1, IoU, false-positive/-negative evidence en reviews |
+| Export | Reproduceerbare GeoJSON- en artefactexports met provenance |
+| Runtime | DockerMan-native Unraid-container met PostGIS, backend en frontend |
+
+## Architectuur
+
+```mermaid
+flowchart LR
+    UI["React + MapLibre workbench"] --> API["FastAPI contracts"]
+    API --> GIS["GeoPandas / Shapely / Rasterio"]
+    API --> JOBS["Job-queue in PostgreSQL"]
+    JOBS --> AI["PyTorch / YOLO / SAM"]
+    GIS --> DB[("PostgreSQL + PostGIS")]
+    AI --> DB
+    DB --> QA["QA/QC + provenance"]
+    QA --> UI
+    QA --> EXPORT["GeoJSON / artifacts"]
+```
+
+De publieke endpoints volgen [docs/API_CONTRACTS.md](docs/API_CONTRACTS.md).
+PostGIS en de persistentieregels volgen
+[docs/DATABASE_IMPLEMENTATION_PLAN.md](docs/DATABASE_IMPLEMENTATION_PLAN.md).
+
+## Stack
+
+- **Frontend:** React 18, TypeScript, MapLibre GL, Lucide en Vite
+- **Backend:** FastAPI en Python
+- **Spatial:** GeoPandas, Shapely, Rasterio, PyProj en GDAL
+- **AI:** PyTorch, Ultralytics YOLO en SAM-compatibele segmentatie
+- **Data:** PostgreSQL/PostGIS, lokale artefactopslag en immutable versions
+- **Jobs:** job-tabel in PostgreSQL met achtergrondworkers in het API-proces
+- **Deployment:** één DockerMan-native Unraid-container
+
+## Lokaal starten
+
+Vereisten: Python 3.11+, Node 20.19+ of 22.12+ en PostgreSQL/PostGIS.
+
+```bash
+python -m pip install -e backend/.[dev]
+cd frontend
+npm install
+npm run start
+```
+
+Voor de volledige lokale stack:
+
+```bash
+docker compose up --build
+```
+
+Open daarna `http://localhost:1202`.
+
+### Gastdemo
+
+Met `GEOINTEL_GUEST_ACCESS_ENABLED=true` biedt de toegangspagina een
+kortlevende, alleen-lezen demosessie. Die toont uitsluitend het ingestelde
+demoproject en bewaard kwaliteitsbewijs; dit is geen multi-user- of
+tenantisolatie.
+
+## NVIDIA/CUDA
+
+Productie-AI gebruikt de NVIDIA GPU van de server. De runtime faalt gesloten
+wanneer CUDA vereist maar niet beschikbaar is; ontbrekende modelconfiguratie
+wordt als `not_configured` getoond en nooit als geslaagde inferentie.
+
+De actuele productieproef draait met een CUDA-build van PyTorch op een NVIDIA
+GeForce RTX 4080 SUPER. Corpus-, kalibratie-, test- en pure-background-gates
+blijven gescheiden: een experimentele label- of modelvariant wordt pas actief
+nadat alle toepasselijke kwaliteitscontroles slagen.
+
+Controleer GPU-zichtbaarheid in de container met:
+
+```bash
+docker exec geointel nvidia-smi
+```
+
+![PyTorch- en NVIDIA-analyseketen](docs/assets/portfolio/geointel-ai-pytorch-pipeline.png)
+
+## Training en labelkwaliteit
+
+GeoIntel behandelt officiële gebouwgrondvlakken niet automatisch als perfecte
+daklabels. Voor trainingsdata worden temporele geldigheid, ruimtelijke leakage,
+bronklasse, zichtbaarheid en pure-background-gedrag afzonderlijk gecontroleerd.
+Een directe polygon-overlay maakt bovendien zichtbaar of de officiële geometrie
+op het bijbehorende luchtbeeld aansluit vóór omzetting naar YOLO-boxen.
+
+De huidige V66 Vlaamse uitbreiding blijft kandidaatdata. Automatische SAM2- en
+edge-alignmentproeven zijn afgewezen omdat ze nog vegetatie, wegen of schaduwen
+als dak konden selecteren. Die resultaten zijn dus niet getraind of gepromoveerd.
+
+## Portfolio case study
+
+De presentatieklare case study combineert productvraag, interface, PyTorch- en
+NVIDIA-keten, architectuur en resultaten in één visueel document:
+
+- [GeoIntel case study PDF](output/pdf/geointel-case-study.pdf)
+- [Donkere cover in hoge resolutie](frontend/public/portfolio/geointel-dark-case-study-cover.png)
+- [Architectuurvisual](docs/assets/portfolio/geointel-architecture.png)
+
+De PDF kan reproduceerbaar opnieuw worden opgebouwd met:
+
+```bash
+python scripts/create_portfolio_case_study.py
+```
+
+## Kwaliteitscontrole
+
+```bash
+# Backend
+python -m compileall backend/app
+cd backend && python -m pytest
+
+# Frontend
+cd frontend
+npm run typecheck
+npm run test:unit
+npm run build
+```
+
+Een wijziging is pas afgerond wanneer de toepasselijke criteria uit
+[docs/DEFINITION_OF_DONE.md](docs/DEFINITION_OF_DONE.md) aantoonbaar zijn
+afgevinkt.
+
+## Tower / Unraid deploy
+
+De canonieke checkout op Tower staat in `/mnt/user/appdata/geointel`. Gebruik
+de releasewrapper; de productiecontainer wordt niet met een alternatieve
+Compose-checkout vervangen.
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/deploy_tower.ps1 `
+  -RemoteHost root@<tower-ip> `
+  -RemotePath /mnt/user/appdata/geointel `
+  -RemoteBranch main `
+  -FrontendUrl http://<tower-ip>:1202
+```
+
+Zie [deploy/unraid/README.md](deploy/unraid/README.md) en
+[docs/RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) voor configuratie,
+healthchecks en rollback.
+
+## Documentatiekaart
+
+- [Start hier](docs/00-start/START_HERE.md)
+- [Belgium/North Sea scope freeze](docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md)
+- [API-contracten](docs/API_CONTRACTS.md)
+- [Database-implementatieplan](docs/DATABASE_IMPLEMENTATION_PLAN.md)
+- [Bekende beperkingen](docs/KNOWN_LIMITATIONS.md)
+- [Release-runbook](docs/RELEASE_RUNBOOK.md)
+
+## Portfolio-assets
+
+De map [`docs/assets/portfolio`](docs/assets/portfolio) bevat presentatieklare
+screenshots, de geanimeerde projectketen, architectuur- en AI-visuals. De drie
+originele campagnebeelden staan in
+[`frontend/public/portfolio`](frontend/public/portfolio). Geoptimaliseerde
+WebP-varianten worden door de applicatie gebruikt; de PNG-bronnen blijven
+beschikbaar voor drukwerk en portfolio-opmaak.
+
+Actuele rasterassets:
+
+| Asset | Gebruik |
+| --- | --- |
+| `geointel-landing-hero.png` | Desktop hero en projectintroductie |
+| `geointel-interactive-story.png` | Vierstappenworkflow en bewijsvoering |
+| `geointel-workbench-map.png` | Kaartgerichte gastwerkruimte |
+| `geointel-workbench-quality.png` | QA/QC, metrics en objectbewijs |
+| `geointel-landing-mobile.png` | Mobiele landing |
+| `geointel-workbench-mobile.png` | Mobiele kaartworkflow |
+
+![GeoIntel mobiele landingspagina](docs/assets/portfolio/geointel-landing-mobile.png)
+
+## Status
+
+Actieve mijlpaal: **v1.0.0 — Belgium and Belgian North Sea**.
+
+GeoIntel is een project van Jens / ITWorx.tech.