> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/generation-3d/gaussian-splatting.md).

# Gaussian Splatting 3D

**Projection gaussienne 3D** est une technique révolutionnaire de reconstruction de scènes 3D en temps réel avec plus de **15 000 étoiles GitHub**. Contrairement aux méthodes basées sur NeRF, la projection gaussienne représente les scènes comme des millions de petites gaussiennes 3D qui peuvent être rendues à **des débits d'images en temps réel** (100+ IPS) tout en atteignant une qualité photoréaliste. Déployez-la sur le cloud GPU de Clore.ai pour reconstruire et explorer des scènes 3D à partir de vos propres photos.

***

## Qu'est-ce que la projection gaussienne 3D ?

Les méthodes NeRF traditionnelles encodent implicitement une scène dans un réseau neuronal, nécessitant un parcours de rayons par pixel au moment du rendu. La projection gaussienne adopte une approche fondamentalement différente :

1. **Initialisation :** Commencer à partir d'un nuage de points clairsemé (depuis COLMAP)
2. **Représentation :** Étendre chaque point en une gaussienne 3D avec position, échelle, rotation, opacité et couleur en harmoniques sphériques
3. **Optimisation :** Rendre différemment les gaussiennes et les optimiser par rapport aux images d'entraînement
4. **Rendu :** Projeter les gaussiennes sur le plan image via un composite alpha (extrêmement rapide)

**Principaux avantages par rapport à NeRF :**

* Rendu en temps réel (100+ IPS en 1080p)
* Meilleure reconstruction des détails fins
* Représentation 3D explicite (modifiable, exportable)
* Entraînement plus rapide (30–60 min vs heures)
* Fonctionne sur des GPU grand public

***

## Prérequis

| Exigence | Minimum        | Recommandé      |
| -------- | -------------- | --------------- |
| VRAM GPU | 12 Go          | 24 Go           |
| GPU      | RTX 3080 12 Go | RTX 4090 / A100 |
| RAM      | 16 Go          | 32 Go           |
| Stockage | 30 Go          | 60 Go           |
| CUDA     | 11.7+          | 12.1+           |

{% hint style="warning" %}
La projection gaussienne a des exigences CUDA strictes. La version de CUDA doit correspondre à l'extension compilée `diff-gaussian-rasterization` fournie. L'utilisation du Dockerfile fourni élimine les problèmes de compatibilité.
{% endhint %}

***

## Étape 1 — Louez un GPU sur Clore.ai

1. Connectez-vous à [clore.ai](https://clore.ai).
2. Cliquez **Place de marché** et filtrez par VRAM ≥ 16 Go.
3. Sélectionnez un serveur — le RTX 4090 offre le meilleur rapport prix/performance.
4. Définissez l'image Docker sur votre image personnalisée (voir l'étape 2).
5. Définir les ports ouverts : `22` (SSH) et `8080` (visionneuse web).
6. Cliquez **Louez**.

***

## Étape 2 — Dockerfile

Construire une image Docker personnalisée avec toutes les dépendances :

```dockerfile
FROM pytorch/pytorch:2.1.2-cuda12.1-cudnn8-devel

ENV DEBIAN_FRONTEND=noninteractive
ENV TORCH_CUDA_ARCH_LIST="6.0;6.1;7.0;7.5;8.0;8.6;8.9;9.0+PTX"

RUN apt-get update && apt-get install -y \
    git wget curl cmake build-essential \
    libboost-program-options-dev libboost-filesystem-dev \
    libboost-graph-dev libboost-system-dev libboost-test-dev \
    libeigen3-dev libflann-dev libfreeimage-dev \
    libmetis-dev libgoogle-glog-dev libgflags-dev \
    libsqlite3-dev libglew-dev qtbase5-dev libqt5opengl5-dev \
    libcgal-dev libceres-dev \
    ffmpeg libgl1 libglib2.0-0 \
    openssh-server \
    python3-pip python3-dev \
    && rm -rf /var/lib/apt/lists/*

# Installer COLMAP
RUN apt-get update && apt-get install -y colmap && rm -rf /var/lib/apt/lists/*

# Configurer SSH
RUN mkdir /var/run/sshd && \
    echo 'root:clore123' | chpasswd && \
    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

WORKDIR /workspace

# Cloner le dépôt 3DGS original
RUN git clone https://github.com/graphdeco-inria/gaussian-splatting /workspace/gaussian-splatting \
    --recursive

# Installer les dépendances Python
RUN cd /workspace/gaussian-splatting && \
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 && \
    pip install -r requirements.txt

# Construire les extensions CUDA
RUN cd /workspace/gaussian-splatting && \
    pip install submodules/diff-gaussian-rasterization && \
    pip install submodules/simple-knn

# Installer les dépendances de la visionneuse web
RUN pip install viser==0.1.29 nerfview==0.0.4 trimesh

EXPOSE 22 8080

CMD service ssh start && tail -f /dev/null
```

### Construire et pousser

Construisez l'image et poussez-la vers votre compte Docker Hub (remplacez `VOTRE_NOM_UTILISATEUR_DOCKERHUB` par votre nom d'utilisateur réel) :

```bash
docker build -t VOTRE_NOM_D_UTILISATEUR_DOCKERHUB/gaussian-splatting:latest .
docker push VOTRE_NOM_D_UTILISATEUR_DOCKERHUB/gaussian-splatting:latest
```

{% hint style="info" %}
Il n'existe pas d'image Docker préconstruite officielle pour la projection gaussienne 3D sur Docker Hub. Le dépôt officiel à [graphdeco-inria/gaussian-splatting](https://github.com/graphdeco-inria/gaussian-splatting) n'en fournit pas — construisez à partir du Dockerfile ci-dessus. L'image doit être construite avec les bons drapeaux d'architecture CUDA correspondant à votre GPU cible.
{% endhint %}

Utilisez `VOTRE_NOM_D_UTILISATEUR_DOCKERHUB/gaussian-splatting:latest` dans votre configuration Clore.ai.

***

## Étape 3 — Connectez-vous via SSH

```bash
ssh root@<clore-host> -p <assigned-ssh-port>
```

Vérifier la construction :

```bash
cd /workspace/gaussian-splatting
python -c "from diff_gaussian_rasterization import GaussianRasterizationSettings; print('CUDA extension OK')"
```

***

## Étape 4 — Préparez votre jeu de données

### Option A : Utiliser le jeu de données Tandt (Tanks and Temples)

Jeu de référence classique pour des tests rapides :

```bash
mkdir -p /workspace/data && cd /workspace/data

# Télécharger une petite scène de test
wget https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/datasets/input/tandt.zip
unzip tandt.zip
```

### Option B : Traiter vos propres photos

```bash
# Télécharger les photos
scp -P <port> -r ./my_photos/ root@<clore-host>:/workspace/data/

# Exécuter le script de traitement COLMAP (fourni avec 3DGS)
cd /workspace/gaussian-splatting

python convert.py \
    -s /workspace/data/my_photos \
    --no_gpu   # optionnel : si le solveur GPU de COLMAP pose problème
```

{% hint style="info" %}
Le `convert.py` le script exécute l'intégralité du pipeline COLMAP : extraction de caractéristiques, appariement, reconstruction sparse et undistortion. Cela prend 5–30 minutes selon le nombre d'images.
{% endhint %}

### Option C : Traiter depuis une vidéo

```bash
# Extraire des images de la vidéo à 2 ips
ffmpeg -i /workspace/data/my_video.mp4 \
    -vf fps=2 \
    /workspace/data/frames/frame_%04d.jpg

# Puis exécuter le traitement COLMAP sur les images extraites
python convert.py -s /workspace/data/frames
```

***

## Étape 5 — Entraîner une projection gaussienne

### Entraînement standard

```bash
cd /workspace/gaussian-splatting

python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --iterations 30000 \
    --eval
```

### Entraînement sur le jeu de données Tandt

```bash
python train.py \
    -s /workspace/data/tandt/truck \
    -m /workspace/output/truck \
    --iterations 30000 \
    --eval
```

### Entraînement rapide (aperçu rapide)

```bash
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene_fast \
    --iterations 7000
```

{% hint style="info" %}
S'entraîner jusqu'à 7 000 itérations prend \~10 minutes sur un RTX 4090 et donne un bon aperçu de qualité. Les 30 000 itérations complètes prennent \~30–40 minutes et produisent la qualité finale.
{% endhint %}

### Progression de l'entraînement

Surveillez la sortie d'entraînement — vous verrez des métriques telles que :

```
[ITER 1000] Évaluation train : L1 0.04, PSNR 26.12 dB
[ITER 7000] Évaluation train : L1 0.02, PSNR 29.45 dB
[ITER 30000] Évaluation train : L1 0.01, PSNR 32.80 dB
```

Un PSNR supérieur à 30 dB indique une reconstruction de haute qualité.

***

## Étape 6 — Rendre et visualiser

### Rendu depuis le modèle entraîné

```bash
python render.py \
    -m /workspace/output/my_scene \
    --skip_train
```

Les rendus sont enregistrés dans `/workspace/output/my_scene/test/ours_30000/renders/`.

### Créer une vidéo de survol (flythrough)

```bash
# Convertir les images rendues en vidéo
ffmpeg -framerate 24 \
    -pattern_type glob \
    -i '/workspace/output/my_scene/test/ours_30000/renders/*.png' \
    -c:v libx264 \
    -pix_fmt yuv420p \
    /workspace/output/flythrough.mp4
```

### Évaluer les métriques

```bash
python metrics.py -m /workspace/output/my_scene
```

Sortie attendue :

```
SSIM : 0.8324
PSNR : 32.81
LPIPS : 0.1893
```

***

## Étape 7 — Visionneuse web interactive

Pour explorer la scène entraînée de manière interactive :

### Utilisation de nerfview/viser

```python
# /workspace/view_splat.py
import viser
import numpy as np
from plyfile import PlyData
import torch

server = viser.ViserServer(host="0.0.0.0", port=8080)
print("Visionneuse en cours d'exécution sur http://0.0.0.0:8080")

# Charger le fichier PLY
ply_path = "/workspace/output/my_scene/point_cloud/iteration_30000/point_cloud.ply"
plydata = PlyData.read(ply_path)

xyz = np.stack([
    plydata['vertex']['x'],
    plydata['vertex']['y'],
    plydata['vertex']['z'],
], axis=-1)

# Ajouter le nuage de points au visualiseur
server.add_point_cloud(
    name="/splat",
    points=xyz,
    colors=np.ones((len(xyz), 3)) * 0.7,
    point_size=0.003,
)

import time
while True:
    time.sleep(0.01)
```

```bash
python /workspace/view_splat.py &
```

Puis ouvrez : `http://<clore-host>:<public-port-8080>`

### Alternative : Utiliser SuperSplat (visionneuse dans le navigateur)

Téléchargez le `.ply` fichier et ouvrez-le dans [SuperSplat](https://playcanvas.com/super-splat):

```bash
# Télécharger depuis votre machine locale
scp -P <port> root@<clore-host>:/workspace/output/my_scene/point_cloud/iteration_30000/point_cloud.ply ./
```

Puis glissez-déposez le `.ply` dans le navigateur SuperSplat à : `https://playcanvas.com/super-splat`

***

## Options avancées

### Contrôler le nombre de gaussiennes

```bash
# Densification plus élevée pour des scènes plus détaillées
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --densify_until_iter 15000 \
    --densify_grad_threshold 0.0002
```

### Fond blanc (pour les objets)

```bash
python train.py \
    -s /workspace/data/my_object \
    -m /workspace/output/my_object \
    --white_background
```

### Scènes à grande échelle

```bash
# Augmenter l'intervalle de réinitialisation d'opacité pour les scènes extérieures
python train.py \
    -s /workspace/data/outdoor \
    -m /workspace/output/outdoor \
    --opacity_reset_interval 5000 \
    --iterations 50000
```

***

## Alternative : Projection gaussienne avec gsplat

`gsplat` est une implémentation plus rapide et économe en mémoire :

```bash
pip install gsplat

# Entraînement avec gsplat
python examples/simple_trainer.py \
    --data_dir /workspace/data/my_photos \
    --result_dir /workspace/gsplat_output
```

***

## Dépannage

### Échec de la compilation de l'extension CUDA

```
error: no kernel image is available for execution on the device
```

**Solution :** Recompiler pour l'architecture GPU spécifique :

```bash
export TORCH_CUDA_ARCH_LIST="8.6"  # Pour RTX 3090/4090
cd /workspace/gaussian-splatting
pip install submodules/diff-gaussian-rasterization --force-reinstall
```

### COLMAP n'arrive pas à reconstruire

**Solutions :**

* Assurez ≥ 50% de recouvrement d'images
* Utilisez plus de photos (100+ recommandé)
* Essayez l'appariement séquentiel pour les images vidéo : ajoutez `--match sequential` à convert.py

### Manque de mémoire pendant l'entraînement

```bash
# Réduire le nombre maximal de gaussiennes
python train.py \
    -s /workspace/data/my_photos \
    -m /workspace/output/my_scene \
    --max_num_splats 2000000  # la valeur par défaut est ~6M
```

### Artefacts flottants dans la scène

Artefacts flottants provenant de l'initialisation des gaussiennes :

* Augmenter `--densify_grad_threshold` pour être plus sélectif
* Utilisez `--prune_opacity_threshold 0.005` pour supprimer plus tôt les gaussiennes de faible opacité

***

## Recommandations GPU Clore.ai

L'entraînement de la projection gaussienne est intensif en calcul GPU avec des appels fréquents aux noyaux CUDA. La VRAM détermine la complexité maximale de la scène (nombre de gaussiennes) ; le calcul détermine la vitesse d'entraînement.

| GPU            | VRAM  | Prix Clore.ai | Entraînement 30K itérations | Gaussiennes max |
| -------------- | ----- | ------------- | --------------------------- | --------------- |
| RTX 3090       | 24 Go | \~0,12 $/h    | \~45–55 min                 | \~6M            |
| RTX 4090       | 24 Go | \~0,70 $/h    | \~30–35 min                 | \~6M            |
| A100 40GB      | 40 Go | \~1,20 $/h    | \~12–18 min                 | \~10M+          |
| RTX 3080 12 Go | 12 Go | \~0,08 $/h    | \~70 min                    | \~3M (limité)   |

{% hint style="info" %}
**Le RTX 3090 à \~0,12 $/h est le meilleur choix** pour la projection gaussienne. Une session complète d'entraînement de 30K itérations coûte \~0,09–0,11 $ en temps GPU. Pour plusieurs scènes dans une même session, le coût est négligeable.

Pour des expériences rapides : entraînez d'abord jusqu'à 7 000 itérations (\~15 min sur RTX 3090, \~0,03 $). Vérifiez la qualité dans la visionneuse web. Lancez les 30K itérations complètes uniquement pour la sortie finale.
{% endhint %}

**Remarque sur le prétraitement COLMAP :** COLMAP (Structure from Motion) s'exécute sur CPU/GPU mais le calcul lourd se fait sur le CPU. La plupart des serveurs Clore.ai disposent de CPU adéquats pour des scènes de moins de 200 images. Pour des jeux de données de 500+ images, recherchez des serveurs avec 16+ cœurs CPU.

***

## Ressources utiles

* [Projection gaussienne 3D GitHub](https://github.com/graphdeco-inria/gaussian-splatting)
* [Article original (SIGGRAPH 2023)](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/)
* [gsplat — Implémentation rapide](https://github.com/nerfstudio-project/gsplat)
* [SuperSplat — Visionneuse navigateur](https://playcanvas.com/super-splat)
* [Communauté Projection Gaussienne (Reddit)](https://www.reddit.com/r/gaussiansplatting/)
* [Awesome Gaussian Splatting](https://github.com/MrNeRF/awesome-3D-gaussian-splatting)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-fr/generation-3d/gaussian-splatting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.