NuklearRabbit
3969a35d7a
Managed validation / Managed repository validation (pull_request) Successful in 1m54s
GeoIntel release gates / Compile, test, contracts and builds (pull_request) Successful in 1m53s
GeoIntel release gates / Python and npm vulnerability policy (pull_request) Failing after 20s
GeoIntel release gates / Production AI image, SBOM and container scan (pull_request) Failing after 12m1s
GeoIntel release gates / Deploy exact gated revision to Unraid (pull_request) Skipped
286 lines
11 KiB
Markdown
286 lines
11 KiB
Markdown
# 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**
|
|
|
|
|
|
|
|
## 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`.
|
|
|
|
|
|
|
|
|
|
|
|
### Kaart als werkruimte
|
|
|
|
De kaart blijft het primaire werkblad. Thema, broncontext, selectie en
|
|
resultaten zijn vanuit dezelfde ruimtelijke context bereikbaar.
|
|
|
|
|
|
|
|
Op een breed scherm krijgt de kaart extra ruimte terwijl de themakolom en de
|
|
controleerbare analysestappen zichtbaar blijven.
|
|
|
|
|
|
|
|
### Kwaliteit vóór resultaat
|
|
|
|
QA/QC is een eerste-klas workflow. Bewaarde controles koppelen scores aan
|
|
objectbewijs, kandidaat- en referentielagen en technische provenance.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
## 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
|
|
```
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
Herkomst en hergebruik van deze bestanden zijn vastgelegd in
|
|
[Asset provenance and redistribution](docs/ASSET_PROVENANCE.md).
|
|
|
|
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 |
|
|
|
|
|
|
|
|
## 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).
|