Add interactive GeoIntel storytelling and portfolio assets
This commit is contained in:
Jens
@@ -1,314 +1,197 @@
|
||||
# GeoIntel Belgium and the Belgian North Sea
|
||||
# GeoIntel
|
||||
|
||||
GeoIntel is a map-first GeoAI Workbench for Belgium and the Belgian North Sea.
|
||||
It combines governed official-source coverage, raster/vector processing,
|
||||
historical comparison, computer vision, QA/QC and geospatial exports.
|
||||
<p align="center">
|
||||
<img src="frontend/public/geointel-icon.png" width="92" alt="GeoIntel logo">
|
||||
</p>
|
||||
|
||||
Mol and the Kempen remain deep regression and model-validation references. The
|
||||
release scope is all of Belgium plus legally labelled Belgian maritime zones;
|
||||
source coverage remains explicit per theme and jurisdiction.
|
||||
<p align="center"><strong>Evidence-first GeoAI voor België en de Belgische Noordzee.</strong></p>
|
||||
|
||||
GeoIntel is not a generic dashboard or chatbot. The core product is:
|
||||
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.
|
||||
|
||||
> data → processing → geospatial output → QA/QC → export
|
||||
> **Data → ruimtelijke verwerking → AI-resultaat → kwaliteitsbewijs → export**
|
||||
|
||||
## Current milestone
|
||||
|
||||
|
||||
**v1.0.0 - Belgium/North Sea release**
|
||||
## Waarom GeoIntel?
|
||||
|
||||
The canonical release controls are:
|
||||
Veel geoportalen tonen lagen. GeoIntel ondersteunt een volledige,
|
||||
controleerbare analyseketen:
|
||||
|
||||
- `docs/00-start/START_HERE.md`
|
||||
- `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md`
|
||||
- `docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md`
|
||||
- `docs/RELEASE_RUNBOOK.md`
|
||||
- `docs/KNOWN_LIMITATIONS.md`
|
||||
- `docs/DEFINITION_OF_DONE.md`
|
||||
- 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.
|
||||
|
||||
Older milestone and sprint handoff files remain historical evidence. They do
|
||||
not override the active national/maritime scope freeze or RC roadmap.
|
||||
Mol en de Kempen blijven de gouden regressiegebieden. De productgrens is heel
|
||||
België plus de juridisch benoemde Belgische maritieme zones.
|
||||
|
||||
## Core V1 vertical slice
|
||||
## Product in beeld
|
||||
|
||||
The first implementation target is:
|
||||
### Interactieve projectketen
|
||||
|
||||
1. Project + Area creation.
|
||||
2. Dataset registration/upload and metadata extraction.
|
||||
3. Reference building layer loading.
|
||||
4. Predicted detection layer loading/import.
|
||||
5. QA/QC matching against reference polygons.
|
||||
6. Metrics and false positive/false negative outputs.
|
||||
7. GeoJSON export.
|
||||
8. Minimal map/workbench UI.
|
||||
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`.
|
||||
|
||||
## Primary stack
|
||||
|
||||
|
||||
- Frontend: React, TypeScript, MapLibre GL, Deck.gl, Tailwind.
|
||||
- Backend: FastAPI, Python.
|
||||
- Database: PostgreSQL + PostGIS.
|
||||
- GIS processing: GeoPandas, Shapely, Rasterio, PyProj, GDAL.
|
||||
- AI: PyTorch, Ultralytics YOLO, SAM-compatible architecture.
|
||||
- Jobs: Redis + RQ.
|
||||
- Storage: local filesystem first, MinIO-compatible later.
|
||||
### Kaart als werkruimte
|
||||
|
||||
## Codex instructions
|
||||
De kaart blijft het primaire werkblad. Thema, broncontext, selectie en
|
||||
resultaten zijn vanuit dezelfde ruimtelijke context bereikbaar.
|
||||
|
||||
Codex must start with:
|
||||
|
||||
|
||||
1. `docs/00-start/START_HERE.md`
|
||||
2. `prompts/codex/M11_ARCHITECT_MASTER_PROMPT.md`
|
||||
### Kwaliteit vóór resultaat
|
||||
|
||||
Then follow the build order in:
|
||||
QA/QC is een eerste-klas workflow. Bewaarde controles koppelen scores aan
|
||||
objectbewijs, kandidaat- en referentielagen en technische provenance.
|
||||
|
||||
- `docs/build/BUILD_ORDER_DEPENDENCY_GRAPH.md`
|
||||
- `docs/build/CODEX_OPERATING_SYSTEM.md`
|
||||
|
||||
|
||||
Before every implementation pass, run available preflight/smoke scripts where applicable.
|
||||
## Kernmogelijkheden
|
||||
|
||||
## Repo principle
|
||||
| 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, Redis, backend en frontend |
|
||||
|
||||
This is a documentation-driven engineering repo. The documentation is not decorative; it is the control system for autonomous implementation.
|
||||
## Architectuur
|
||||
|
||||
## Fastest Day 1 command path
|
||||
|
||||
```bash
|
||||
make readiness
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI["React + MapLibre workbench"] --> API["FastAPI contracts"]
|
||||
API --> GIS["GeoPandas / Shapely / Rasterio"]
|
||||
API --> JOBS["Redis + RQ"]
|
||||
JOBS --> AI["PyTorch / YOLO / SAM"]
|
||||
GIS --> DB[("PostgreSQL + PostGIS")]
|
||||
AI --> DB
|
||||
DB --> QA["QA/QC + provenance"]
|
||||
QA --> UI
|
||||
QA --> EXPORT["GeoJSON / artifacts"]
|
||||
```
|
||||
|
||||
## Unraid / Tower deployment
|
||||
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).
|
||||
|
||||
GeoIntel runs on Unraid as an all-in-one DockerMan-native container. The container embeds PostGIS, runs the FastAPI backend internally, and serves the frontend through nginx on one editable web port.
|
||||
## Stack
|
||||
|
||||
Unraid template assets live in:
|
||||
- **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:** Redis en RQ
|
||||
- **Deployment:** één DockerMan-native Unraid-container
|
||||
|
||||
- `deploy/unraid/geointel.env.example`
|
||||
- `deploy/unraid/geointel-unraid-template.xml`
|
||||
- `deploy/unraid/geointel-icon.svg`
|
||||
- `deploy/unraid/geointel-icon.png`
|
||||
- `docker-compose.unraid.yml`
|
||||
## Lokaal starten
|
||||
|
||||
Copy the Unraid env template to `.env` in the checkout and edit ports/paths there:
|
||||
|
||||
```bash
|
||||
cd /mnt/user/appdata/geointel
|
||||
cp deploy/unraid/geointel.env.example .env
|
||||
nano .env
|
||||
docker build -f deploy/unraid/Dockerfile.all-in-one -t geointel-all-in-one:latest .
|
||||
bash deploy/unraid/run-dockerman-container.sh
|
||||
```
|
||||
|
||||
Common editable values:
|
||||
|
||||
```env
|
||||
GEOINTEL_FRONTEND_PORT=1202
|
||||
GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage
|
||||
GEOINTEL_POSTGIS_DATA_PATH=/mnt/user/appdata/geointel/postgres-data
|
||||
```
|
||||
|
||||
### Guest demonstration access
|
||||
|
||||
Guest access is enabled by default whenever the operator login gate is active.
|
||||
No additional guest toggle is required for a new authenticated installation:
|
||||
|
||||
```env
|
||||
GEOINTEL_AUTH_ENABLED=true
|
||||
GEOINTEL_AUTH_USERNAME=operator
|
||||
GEOINTEL_AUTH_PASSWORD_HASH=pbkdf2_sha256$...
|
||||
GEOINTEL_AUTH_SESSION_SECRET=<independent-random-secret-of-at-least-32-characters>
|
||||
GEOINTEL_GUEST_ACCESS_ENABLED=true
|
||||
GEOINTEL_GUEST_DISPLAY_NAME=Gast
|
||||
GEOINTEL_GUEST_SESSION_TTL_SECONDS=7200
|
||||
```
|
||||
|
||||
The login page offers **Als gast verkennen**. A guest receives a short-lived,
|
||||
read-only session scoped to the seeded demo project and sees only the map and
|
||||
existing quality evidence. Set `GEOINTEL_GUEST_ACCESS_ENABLED=false` to hide and
|
||||
disable this route. This is not multi-user authorization or tenant isolation;
|
||||
use a separate demo instance when the installation contains private or
|
||||
operational datasets.
|
||||
|
||||
The backend and PostGIS ports are intentionally not exposed to the LAN in the all-in-one runtime. See `deploy/unraid/README.md` for full setup, port-change and cleanup notes.
|
||||
|
||||
On Tower/Unraid, `scripts/deploy_tower.ps1` and `scripts/deploy_tower.sh` validate the Compose reference but build with plain `docker build`, then automatically install the editable DockerMan template as `/boot/config/plugins/dockerMan/templates-user/my-geointel.xml`, install the PNG icon as `/boot/config/plugins/dockerMan/images/geointel-icon.png`, remove any old Compose-owned `geointel` container and start the final container with DockerMan labels.
|
||||
|
||||
## Sprint 2 quick start
|
||||
|
||||
- Update dependencies:
|
||||
Vereisten: Python 3.11+, Node 20.19+ of 22.12+, PostgreSQL/PostGIS en Redis.
|
||||
|
||||
```bash
|
||||
python -m pip install -e backend/.[dev]
|
||||
cd frontend && npm install
|
||||
cd frontend
|
||||
npm install
|
||||
npm run start
|
||||
```
|
||||
|
||||
- Run full readiness checks (with no scope expansion):
|
||||
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.
|
||||
|
||||
Controleer GPU-zichtbaarheid in de container met:
|
||||
|
||||
```bash
|
||||
docker exec geointel nvidia-smi
|
||||
```
|
||||
|
||||
## Kwaliteitscontrole
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
python -m compileall backend/app
|
||||
cd backend && python -m pytest
|
||||
cd ../frontend && npm run typecheck && npm run build
|
||||
bash scripts/run_readiness_check.sh
|
||||
```
|
||||
|
||||
- Raster workflow validation command (backend only):
|
||||
|
||||
```bash
|
||||
bash scripts/smoke_backend_import.sh
|
||||
cd backend && python -c "from app.main import app; print(app.title)"
|
||||
```
|
||||
|
||||
If `rasterio` is not installed, raster metadata endpoints return `RASTER_PROCESSING_UNAVAILABLE` and the frontend displays the
|
||||
state as failed until the dependency is added.
|
||||
|
||||
## Sprint 4 raster foundation
|
||||
|
||||
- Raster operations now support:
|
||||
- raster metadata extraction,
|
||||
- raster preview generation,
|
||||
- raster clip by area (with provenance on derived datasets),
|
||||
- raster tile generation with manifest output.
|
||||
- Raster services are dependency-aware:
|
||||
- if `rasterio` is unavailable, endpoints return `RASTER_PROCESSING_UNAVAILABLE`.
|
||||
- if preview dependencies (`numpy`, `pillow`) are unavailable, preview generation is unavailable with a clear error.
|
||||
- Enable raster stack explicitly when needed:
|
||||
|
||||
```bash
|
||||
cd backend && python -m pip install -e .[dev,raster]
|
||||
```
|
||||
|
||||
## Sprint 5 raster analytics hardening
|
||||
|
||||
- Added raster band statistics (min/max/mean/std, nodata ratio/count, valid pixel count, dtype, optional histograms).
|
||||
- Added raster reproject workflow with CRS validation and provenance persistence.
|
||||
- Extended tile manifest expectations (`tile_set_id`, `tile_size`, `overlap`, `bounds`, `source_raster_id`, `tile_paths`, `tile_server`).
|
||||
- Clarified raster operation availability in frontend/backend docs (`RASTER_PROCESSING_UNAVAILABLE` and invalid-CRS cases).
|
||||
|
||||
- Raster workflow command set (where available):
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python -m pip install -e .[dev,raster]
|
||||
python -m pytest
|
||||
cd ../frontend
|
||||
# Frontend
|
||||
cd frontend
|
||||
npm run typecheck
|
||||
npm run test:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
Then give Codex the prompt in:
|
||||
Een wijziging is pas afgerond wanneer de toepasselijke criteria uit
|
||||
[docs/DEFINITION_OF_DONE.md](docs/DEFINITION_OF_DONE.md) aantoonbaar zijn
|
||||
afgevinkt.
|
||||
|
||||
- `prompts/codex/final/DAY_1_MASTER_PROMPT.md`
|
||||
## 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.
|
||||
|
||||
## M13 Codex optimization
|
||||
|
||||
For the first serious Codex build run, use:
|
||||
|
||||
- `prompts/codex/m13/DAY_1_OPTIMIZED_MASTER_PROMPT.md`
|
||||
|
||||
Codex should also use the relevant reusable skill under `skills/` for each implementation pass. Validate the optimization assets with:
|
||||
|
||||
```bash
|
||||
make m13
|
||||
```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
|
||||
```
|
||||
|
||||
The full readiness path remains:
|
||||
Zie [deploy/unraid/README.md](deploy/unraid/README.md) en
|
||||
[docs/RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) voor configuratie,
|
||||
healthchecks en rollback.
|
||||
|
||||
```bash
|
||||
make readiness
|
||||
```
|
||||
## 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)
|
||||
|
||||
## M14 Build Launch
|
||||
## Portfolio-assets
|
||||
|
||||
For the first serious implementation run, use:
|
||||
De map [`docs/assets/portfolio`](docs/assets/portfolio) bevat presentatieklare
|
||||
screenshots van de landingspagina, interactieve illustratie, kaartwerkruimte,
|
||||
kwaliteitscontrole en mobiele weergave. De twee originele campagnebeelden
|
||||
staan in [`frontend/public/portfolio`](frontend/public/portfolio) en worden
|
||||
ook door de applicatie gebruikt.
|
||||
|
||||
- `docs/40-build-launch/SPRINT_1_SCOPE_FREEZE.md`
|
||||
- `docs/40-build-launch/BUILD_SUCCESS_DEFINITION.md`
|
||||
- `docs/40-build-launch/CODEX_STOP_RULES.md`
|
||||
- `prompts/codex/m14/CODEX_FIRST_DAY_MASTER_PROMPT.md`
|
||||
|
||||
|
||||
Validate launch assets with:
|
||||
## Status
|
||||
|
||||
```bash
|
||||
make m14
|
||||
```
|
||||
Actieve mijlpaal: **v1.0.0 — Belgium and Belgian North Sea**.
|
||||
|
||||
Full readiness remains:
|
||||
|
||||
```bash
|
||||
make readiness
|
||||
```
|
||||
|
||||
## Sprint 1 execution (Sprint 1 only)
|
||||
|
||||
From a clean machine:
|
||||
|
||||
```bash
|
||||
cd backend && python -m pip install -e .[dev]
|
||||
cd ..
|
||||
make backend-install
|
||||
make frontend-install
|
||||
make readiness
|
||||
```
|
||||
|
||||
Copy `.env.example` to `.env` only when you want local overrides. Docker Compose has safe defaults for the local PostGIS/backend/frontend stack and does not require a root `.env` file to exist.
|
||||
|
||||
With Docker Compose, open the workbench at `http://localhost:1202`.
|
||||
|
||||
The Docker frontend is served by nginx and proxies `/api` and `/health` to the backend container, so browser clients should use the frontend URL only, for example `http://192.168.10.150:1202` on a LAN host.
|
||||
|
||||
Runtime containers include healthchecks for PostGIS, backend and frontend. After
|
||||
startup, inspect them with:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Verify the browser-facing API proxy after rebuilding Docker images:
|
||||
|
||||
```bash
|
||||
bash scripts/verify_browser_runtime.sh http://localhost:1202 http://localhost:8000/health
|
||||
```
|
||||
|
||||
Verify the Docker GIS runtime after rebuilding the backend image:
|
||||
|
||||
```bash
|
||||
bash scripts/verify_gis_runtime.sh http://localhost:1202
|
||||
```
|
||||
|
||||
On the LAN host use the published browser URL, for example:
|
||||
|
||||
```bash
|
||||
bash scripts/verify_gis_runtime.sh http://192.168.10.150:1202
|
||||
```
|
||||
|
||||
Load the explicit offline demo workflow:
|
||||
|
||||
```bash
|
||||
curl -X POST http://192.168.10.150:1202/api/v1/demo/workflow
|
||||
```
|
||||
|
||||
If `/api/v1/projects` returns frontend HTML instead of a JSON envelope, rebuild
|
||||
and restart the frontend container.
|
||||
|
||||
Useful direct verification commands:
|
||||
|
||||
```bash
|
||||
python -m compileall backend/app
|
||||
cd backend && python -c "from app.main import app; print(app.title)"
|
||||
python -m pytest
|
||||
cd ../frontend && npm run typecheck
|
||||
cd ../frontend && npm run build
|
||||
docker compose config
|
||||
bash scripts/run_readiness_check.sh
|
||||
```
|
||||
|
||||
If `make` or `docker` are unavailable in your shell, run the equivalent script entrypoints directly:
|
||||
|
||||
```bash
|
||||
bash scripts/backend_install.sh
|
||||
bash scripts/backend_test.sh
|
||||
bash scripts/frontend_install.sh
|
||||
bash scripts/frontend_typecheck.sh
|
||||
bash scripts/frontend_build.sh
|
||||
bash scripts/run_readiness_check.sh
|
||||
```
|
||||
GeoIntel is een project van Jens / ITWorx.tech.
|
||||
|
||||
Reference in New Issue
Block a user