Plateforme 3D Gaussian Splatting (3DGS) & Protocole de Benchmark POC (v2.1)

Ce dépôt implémente l'architecture modulaire et le banc de test expérimental quantitatif définis dans le protocole v2.1.

1. Architecture Modulaire

Le pipeline sépare rigoureusement la métadonnée du calcul lourd GPU et assure un flux d'artefacts continu :

preproc.py : Extraction vidéo et filtrage de netteté par variance du Laplacien (H1).
sfm.py : Reconstruction SfM COLMAP 4, stratégies de matching (H2a), mapping incrémental vs global (H2b), et séparation spatial/trajectoire des vues test.
engine.py : Entraînement 3DGS comparant gsplat et Brush (H3) avec suivi multidimensionnel (convergence, time-to-quality, pic VRAM, Gaussiennes).
postproc.py : Compression multi-formats (H4 : PLY, SPZ, SOG, Streamed SOG) et audit de compatibilité SuperSplat Viewer.
collision.py : Collision Asset Generator (génération d'occupancy voxélisée .voxel et mesh simplifié pour le Walk Mode du viewer).
exporter.py : PointCloud Exporter (.xyz pour Archicad et .e57 pour ReCap/Revit).
metrology.py : Triplet radiométrique (PSNR, SSIM, LPIPS), opérateur de mesure géométrique 3DGS (raycast), calibration $D_{calib}$ + RMSE sur cotes de contrôle 3D non-coplanaires, et recalage temporel ICP (distinction résidu ICP vs vérité terrain statique).
pareto.py : Algorithme d'analyse multi-objectifs pour identifier les configurations non dominées et choisir les gagnants du POC sans biais arbitraire.
pipeline.py : Orchestrateur worker de bout en bout reliant S3/raw -> Worker -> S3/artifacts.
cli.py : Interface en ligne de commande pour piloter la matrice de tests et les jobs.

2. Guide d'Exécution & Commandes CLI

Exécuter la suite de tests et vérifications de conformité

python tests/test_core.py
# ou via pytest
pytest tests/

Lancer la matrice de benchmark expérimentale (H1 - H4)

python -m gs_platform.cli run-matrix --input /chemin/vers/video_ou_images --output ./resultats_benchmark --iterations 30000 --seeds 42,1337

Calculer le front de Pareto et les recommandations du POC

python -m gs_platform.cli pareto --file ./resultats_benchmark/matrix_benchmark_results.json

Exécuter un job de traitement complet de bout en bout

python -m gs_platform.cli run-job --input /chemin/vers/video_ou_images --output ./artifacts_s3 --job-id chantier_bat_a_t0

Project: 3DGS AEC v2.2 Upgrade & Technical Audit Remediation

Architecture

The 3DGS AEC platform v2.2 is structured as a modular Python package (gs_platform) integrating photogrammetry, Gaussian splatting, AEC metrology, BIM point cloud export, and WebGPU/Three.js interactive viewing:

Preprocessing (src/gs_platform/preproc.py): Video frame extraction (1.5-2.0 FPS), blur detection via BT.601 Laplacian variance filtering (production default laplacian_threshold = 5.0), and image dataset conditioning.
Structure-from-Motion (src/gs_platform/sfm.py): COLMAP 4.2.0 runner, sparse feature extraction & matching, camera calibration, unified global mapping (production default mapper_type = "global"), and leak-free trajectory test split with guard margin.
Core Reconstruction Engine (src/gs_platform/engine.py): 3DGS / 2DGS / MCMC training coordination via Brush CLI (tools/brush/brush_app.exe, absolute repo-anchored path) with anti-leak PLY deletion, 0-views validation, multi-checkpoint --export-name "splat_{iter}.ply", and deterministic synthetic simulation.
Metrology & QA (src/gs_platform/metrology.py): RANSAC plane fitting, SVD refinement, wall planarity estimation, residual distribution ($P_{95}$ wall thickness in mm), and outlier ratio calculation.
BIM & Point Cloud Exporter (src/gs_platform/exporter.py): Conversion of Gaussian / Surfel models to oriented point clouds (.ply, .xyz, .e57) with cartesian (cartesianX, Y, Z) and analytical normal (norX, Y, Z) channels conforming to ASTM E2807.
WebGPU / Three.js Viewer (src/gs_platform/viewer.py): Interactive 3D viewer featuring Z-buffer depth testing, spatial occlusion between 3DGS surfels and reference BIM solid virtual geometries.
Pipeline Orchestrator & CLI (src/gs_platform/pipeline.py, src/gs_platform/cli.py): End-to-end execution, ablation benchmarking matrix, and structured scalability telemetry logging (scalability_report.json).

Feature Inventory

#	Feature	Description	Milestone	Source
1	`strategy="2dgs"` support	Flat 2D surfel disks with collapsed normal scale ($s_2 \le 0.1$ mm) and closed-form unitary orientation quaternions	M1	ORIGINAL_REQUEST §R1
2	`strategy="mcmc"` support	MCMC densification and sample redistribution yielding high-density surface coverage ($\sigma \le 2.0$ mm)	M1	ORIGINAL_REQUEST §R1
3	Metrological wall thickness $P_{95} < 15.0$ mm	Sub-15mm wall thickness measured by RANSAC plane fitting in `evaluate_wall_planarity`	M1	ORIGINAL_REQUEST §R1
4	Unitary surface normals	Exact $\|n\| = 1.0$ analytical normals aligned with local planar geometry	M1	ORIGINAL_REQUEST §R1
5	Large video processing (`IMG_4497.MOV`)	Robust processing of 679 Mo 4K 60fps video at 1.5 - 2.0 FPS with BT.601 Laplacian variance filtering (threshold 15.0)	M2	ORIGINAL_REQUEST §R2
6	Leak-free COLMAP trajectory split	Temporal separation between train and test views with `guard_margin >= 1` preventing consecutive frame contamination	M2	ORIGINAL_REQUEST §R2
7	Memory safety & Scalability telemetry	Absence of CUDA/system OOM (peak VRAM ~2.15 GB), and structured reporting via `scalability_report.json`	M2	ORIGINAL_REQUEST §R2
8	WebGPU / Three.js Z-buffer depth occlusion	Interactive viewer rendering solid BIM reference objects and 3DGS surfels with active Z-buffer depth testing and occlusion toggles	M3	ORIGINAL_REQUEST §R3
9	ASTM E57 exporter with analytical normals	Standard E57 export with 48-byte ASTM E2807 header, `cartesianX, Y, Z` and `norX, Y, Z` channels for ReCap / Revit	M3	ORIGINAL_REQUEST §R3
10	100% Core compliance test pass	Full passing suite in `tests/test_core.py` with added unit tests for 2DGS/MCMC, leak-free split, Z-buffer occlusion, and E57 header/channels	M3	ORIGINAL_REQUEST §R3
11	Opaque-box 4-tier E2E testing suite	Independent 4-tier requirement-driven E2E test suite published with `TEST_READY.md`	E2E	Dual Track Pattern
12	100% E2E test pass & adversarial hardening	Phase 1: 100% pass on Tiers 1-4. Phase 2: Tier 5 adversarial white-box coverage hardening	M4	Final Milestone
13	R1: Engine P0 anti-leak & safety	Purge `splat_*.ply` in output_dir before launch, check `st_mtime >= start_epoch`, raise `RuntimeError` on 0 views, absolute repo-relative exe path, explicit `"simulated": true` in metrics	M_Audit_1	ORIGINAL_REQUEST §Audit R1
14	R2: Checkpoint management & PLY exports	Pass `--export-name "splat_{iter}.ply"`, resolve final PLY by max iter name, deduce `completed_iters`, count real gaussians (`read_ply_header_and_count`) for each checkpoint	M_Audit_1	ORIGINAL_REQUEST §Audit R2
15	R4: Production SfM & Preproc defaults	`SfmConfig.mapper_type = "global"`, `PreprocConfig.laplacian_threshold = 5.0`, CLI `--blur-threshold 5.0`, update tests & add pipeline integration test	M_Audit_2	ORIGINAL_REQUEST §Audit R4
16	R3: Empirical noise floor 3 seeds @ 15k	Evaluate seeds 42, 43, 44 at 15 000 iters on 77-view model, compute mean, std dev, max delta in `benchmark_ablation/noise_floor_15k.json`, update `NOISE_FLOOR_PSNR_DB`	M_Audit_3	ORIGINAL_REQUEST §Audit R3
17	Global regression verification & audit	All >= 227 tests passing + new adverse tests, complete clean forensic audit	M_Audit_4	ORIGINAL_REQUEST §Acceptance

Milestones

#	Name	Scope	Dependencies	Status
M1	2DGS & MCMC Metrology Engine	Implement `strategy="2dgs"` and `strategy="mcmc"` in `engine.py`	none	DONE
M2	Scalability & Video Pipeline	Integrate 1.5-2.0 FPS sampling + Laplacian filter in `preproc.py`	none	DONE
M3	BIM Interoperability & WebGPU Viewer	Implement solid virtual BIM reference objects and surfel depth testing	M1	DONE
E2E	E2E Testing Track	Independent opaque-box test runner and 4-tier test cases	none	DONE
M4	Final Milestone & Coverage Hardening	100% pass of E2E test suite & Tier 5 hardening	M1, M2, M3, E2E	DONE
M_Audit_1	Engine Safety & Checkpoints	Implement R1 & R2: anti-leak PLY, 0-views detection, repo-relative exe, simulated flag, splat_{iter}.ply, checkpoints gaussian count	none	DONE
M_Audit_2	Production SfM & Preproc Defaults	Implement R4: SfmConfig mapper_type="global", PreprocConfig laplacian_threshold=5.0, CLI defaults, test adjustments, pipeline integration test	none	DONE
M_Audit_3	Empirical Noise Floor Measurement	Implement R3: Run seeds 43 & 44 @ 15k, record noise_floor_15k.json, update NOISE_FLOOR_PSNR_DB and test assertions	none	DONE
M_Audit_4	Global Verification & Audit	Validate full test suite (>= 227 tests), verify adverse tests, perform forensic integrity audit	M_Audit_1, M_Audit_2, M_Audit_3	DONE

Interface Contracts

`engine.py` ↔ `pipeline.py` & CLI

EngineConfig:
- engine_type: str: resolved via absolute path Path(__file__).resolve().parents[2] / "tools" / "brush" / "brush_app.exe"
- simulate: bool: when True, sets res.simulated = True and writes "simulated": true in JSON metrics.
EngineResult:
- simulated: bool = False
- completed_iters: int (deduced from filename splat_{iter}.ply)
- checkpoints: List[Dict[str, Any]] where each checkpoint dictionary has "iteration", "ply_filename", "gaussian_count" (from read_ply_header_and_count).
run_training_engine:
- Raises RuntimeError if n_train_views is None or n_train_views == 0.
- Raises EngineOutputNotFoundError if no PLY produced with st_mtime >= start_epoch.

`sfm.py` ↔ `preproc.py` ↔ `cli.py`

SfmConfig.mapper_type: default is "global".
PreprocConfig.laplacian_threshold: default is 5.0.
cli.py: --blur-threshold default is 5.0.

Code Layout

src/gs_platform/: Production source code
- src/gs_platform/engine.py (owned by M_Audit_1 Worker, M_Audit_3 Worker for NOISE_FLOOR_PSNR_DB)
- src/gs_platform/pipeline.py (owned by M_Audit_1 Worker & M_Audit_2 Worker)
- src/gs_platform/preproc.py (owned by M_Audit_2 Worker)
- src/gs_platform/sfm.py (owned by M_Audit_2 Worker)
- src/gs_platform/cli.py (owned by M_Audit_2 Worker)
tests/: Automated test suites
- tests/test_adversarial_point4.py
- tests/test_adversarial_point3_challenger2.py
- tests/e2e/tier1_features/test_f5_fps_sampling.py
- tests/test_core.py
- tests/test_production_sfm_preproc_defaults.py (new integration test)
benchmark_ablation/:
- benchmark_ablation/noise_floor_15k.json (owned by M_Audit_3 Worker)

3D Gaussian Splatting Architecture

Démarrer

Jalons

Documentation

Plateforme 3D Gaussian Splatting (3DGS) & Protocole de Benchmark POC (v2.1)

1. Architecture Modulaire

2. Guide d'Exécution & Commandes CLI

Exécuter la suite de tests et vérifications de conformité

Lancer la matrice de benchmark expérimentale (H1 - H4)

Calculer le front de Pareto et les recommandations du POC

Exécuter un job de traitement complet de bout en bout

Project: 3DGS AEC v2.2 Upgrade & Technical Audit Remediation

Architecture

Feature Inventory

Milestones

Interface Contracts

`engine.py` ↔ `pipeline.py` & CLI

`sfm.py` ↔ `preproc.py` ↔ `cli.py`

Code Layout

Démarrer

Jalons

Documentation

Plateforme 3D Gaussian Splatting (3DGS) & Protocole de Benchmark POC (v2.1)

1. Architecture Modulaire

2. Guide d'Exécution & Commandes CLI

Exécuter la suite de tests et vérifications de conformité

Lancer la matrice de benchmark expérimentale (H1 - H4)

Calculer le front de Pareto et les recommandations du POC

Exécuter un job de traitement complet de bout en bout

Project: 3DGS AEC v2.2 Upgrade & Technical Audit Remediation

Architecture

Feature Inventory

Milestones

Interface Contracts

engine.py ↔ pipeline.py & CLI

sfm.py ↔ preproc.py ↔ cli.py

Code Layout

`engine.py` ↔ `pipeline.py` & CLI

`sfm.py` ↔ `preproc.py` ↔ `cli.py`