From 82458b4d29b934c8da019f2f44606fb7191e1344 Mon Sep 17 00:00:00 2001 From: Jens Caers Date: Wed, 26 Aug 2026 21:35:56 +0200 Subject: [PATCH] repo: restore README after branch-only tool error --- README.md | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 267 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a8b6c947..2e5a78f2 100644 --- a/README.md +++ b/README.md @@ -1 +1,267 @@ -noop \ No newline at end of file +# 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). + +

+ GeoIntel logo +

+ +

Evidence-first GeoAI voor België en de Belgische Noordzee.

+ +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@ ` + -RemotePath /mnt/user/appdata/geointel ` + -RemoteBranch main ` + -FrontendUrl http://: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.