Initial public release

2026-08-31 21:56:53 +02:00
commit faeb58ef6d
1386 changed files with 263203 additions and 0 deletions
@@ -0,0 +1,282 @@
+# GeoIntel
+
+<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 tonen de huidige applicatie met publieke
+demodata. De gastmodus toont een projectgebonden demowerkruimte
+met dezelfde kaart-, bron-, model-, analyse-, QA- en exportflow als een
+operator. Alleen beheer, instellingen, uploads, bronconfiguratie,
+projectbeheer en evidence-review 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)
+
+Op een breed scherm krijgt de kaart extra ruimte terwijl de themakolom en de
+controleerbare analysestappen zichtbaar blijven.
+
+![GeoIntel brede kaartwerkruimte](docs/assets/portfolio/geointel-workbench-wide.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_AUTH_ENABLED=true` en de expliciete opt-in
+`GEOINTEL_GUEST_ACCESS_ENABLED=true` biedt de toegangspagina een
+kortlevende, projectgebonden demosessie. De gast heeft binnen het ingestelde
+demoproject dezelfde kaart-, bronselectie-, modelselectie-, analyse-, QA- en
+exportmogelijkheden als een operator. Alleen beheerfuncties zoals instellingen,
+uploads, bronconfiguratie, projectbeheer en evidence-review blijven geblokkeerd;
+dit is geen multi-user- of tenantisolatie. Gasttoegang staat standaard uit en
+hoort alleen op een aparte demo-installatie met publieke data.
+
+Een optionele Authentik OIDC-login kan naast de lokale operatorlogin worden
+ingeschakeld. GeoIntel gebruikt daarbij PKCE, state, nonce, issuer-/audience-
+controle en één expliciet toegelaten, geverifieerd e-mailadres. De lokale
+operatorlogin blijft altijd het herstelpad.
+
+## 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.
+
+Corpus-, kalibratie-, test- en pure-background-gates blijven gescheiden: een
+experimentele label- of modelvariant wordt pas actief nadat alle toepasselijke
+kwaliteitscontroles slagen. Exacte runtime- en hardwaregegevens horen bij de
+lokale deployment, niet bij de publieke broncode.
+
+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. Voor
+productresultaten blijft de taakgeschikte officiële bron doorslaggevend; een
+AI-detectie is controleerbaar voorstelbewijs zolang een taakgebonden releasegate
+niet aantoonbaar anders beslist.
+
+Modelactivatie vereist naast het oudere diagnostische promotierapport ook een
+geslaagd, governed Phase-4/5 release-gaterapport dat exact dezelfde candidate
+key, model-SHA-256 en benchmarkmanifest-SHA-256 bindt. Zie
+[Accuracy, modelgrenzen en bewijs](docs/ACCURACY.md). Er wordt geen
+100%-accuratieclaim gemaakt; modeloutput blijft controleerbaar voorstelbewijs.
+
+## 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.
+
+## Unraid-deployment
+
+De ondersteunde productieopstelling bundelt PostGIS, backend en frontend in één
+Unraid-container. Kopieer de voorbeeldconfiguratie, vul de verplichte
+authenticatie- en opslaginstellingen in en gebruik de releaseworkflow met
+backup-, healthcheck- en rollbackcontrole.
+
+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)
+- [Actieve release-roadmap](docs/RC_ROADMAP_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-wide.png` | Brede kaartwerkruimte voor desktopportfolio's |
+| `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.
+
+## Licentie
+
+GeoIntel is beschikbaar onder de [Apache License 2.0](LICENSE).