Nerfstudio - Reconstruction 3D par Neural Radiance Fields¶

Nerfstudio est un framework open-source pour créer des modèles 3D photoréalistes à partir de photos.

Vue d'ensemble¶

Paramètre	Valeur
URL	http://192.168.1.82:7007
Port	7007
GPU	2× RTX 5090 (64 GB VRAM each)
Data	`/data/nerfstudio/`
Install	`/opt/nerfstudio/`
User	`nerfstudio` (system)

Architecture¶

┌────────────────────────────────────────────┐
│  Photos (50-200)                           │
│  - JPEG/PNG                                │
│  - 360° coverage                           │
└──────────────┬─────────────────────────────┘
               │
               ▼
┌────────────────────────────────────────────┐
│  COLMAP (Structure-from-Motion)            │
│  - Calcul poses caméra                     │
│  - Calibration automatique                 │
└──────────────┬─────────────────────────────┘
               │
               ▼
┌────────────────────────────────────────────┐
│  Training NeRF (10-30 min RTX 5090)        │
│  - nerfacto (balanced)                     │
│  - instant-ngp (ultra-fast)                │
│  - splatfacto (Gaussian Splatting)         │
└──────────────┬─────────────────────────────┘
               │
               ▼
┌────────────────────────────────────────────┐
│  Output                                    │
│  - Viewer 3D interactif (port 7007)        │
│  - Export mesh (.obj, .ply)                │
│  - Vidéos flythrough                       │
└────────────────────────────────────────────┘

Installation¶

Déployé automatiquement via GitLab CI/CD :

cd /opt/probatiovault-ia-server/ansible
ansible-playbook -i inventory/hosts playbooks/install-nerfstudio.yml

Durée : ~5-8 minutes (téléchargement packages)

Premier démarrage¶

1. Dataset d'exemple (LEGO poster)¶

Un dataset d'exemple est téléchargé automatiquement :

ls /data/nerfstudio/data/nerfstudio/poster/
# images/  (100 photos d'un poster LEGO)
# transforms.json (poses caméra pré-calculées)

2. Lancer un training¶

cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/nerfstudio/poster nerfacto

Output :

🚀 Training NeRF with method: nerfacto
📁 Dataset: /data/nerfstudio/data/nerfstudio/poster
──────────────────────────────────────────────────────────────────
Starting training on poster dataset
Step 0: loss=0.5234, PSNR=18.2 dB
Step 100: loss=0.1234, PSNR=25.7 dB
Step 500: loss=0.0234, PSNR=32.1 dB
Step 1000: loss=0.0089, PSNR=35.4 dB ✅
Training complete! (15min 32s)

Viewer running at: http://192.168.1.82:7007

3. Ouvrir le viewer¶

Naviguer vers http://192.168.1.82:7007

Interface : - Rotation 3D (souris) - Zoom (molette) - Export mesh (bouton) - Changement de caméra - Réglages qualité (samples, résolution)

Workflow complet¶

Étape 1 : Prendre des photos¶

Recommandations : - 50-200 photos (plus = meilleur, mais plus lent) - Couvrir tous les angles (360° si possible) - Éclairage stable (pas de variation entre photos) - Éviter le flou (trépied ou vitesse élevée) - Format : JPEG ou PNG (résolution ≥ 1080p)

Exemples d'objets : - ✅ Objets opaques (sculptures, meubles, produits) - ✅ Environnements (pièces, bâtiments, jardins) - ⚠️ Objets transparents (verre, plastique) → résultats moyens - ❌ Objets très réfléchissants (miroirs, chrome) → difficile

Étape 2 : Uploader les photos¶

# Créer un dossier pour votre scène
mkdir -p /data/nerfstudio/data/my-scene/images

# Copier vos photos
cp /chemin/vers/photos/*.jpg /data/nerfstudio/data/my-scene/images/

# Vérifier
ls /data/nerfstudio/data/my-scene/images/
# IMG_001.jpg, IMG_002.jpg, ...

Étape 3 : Lancer le training¶

Méthode 1 : Nerfacto (balanced, recommandé)

cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/my-scene nerfacto

Qualité : ⭐⭐⭐⭐ (excellent)
Vitesse : 15-30 min sur RTX 5090
VRAM : ~8-12 GB
Cas d'usage : Général (objets, scènes)

Méthode 2 : Instant-NGP (ultra-fast)

cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/my-scene instant-ngp

Qualité : ⭐⭐⭐ (bon)
Vitesse : 5-10 min sur RTX 5090
VRAM : ~4-6 GB
Cas d'usage : Prototypage rapide, previews

Méthode 3 : Splatfacto (Gaussian Splatting, best quality)

cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/my-scene splatfacto

Qualité : ⭐⭐⭐⭐⭐ (photoréaliste)
Vitesse : 10-20 min sur RTX 5090
VRAM : ~15-20 GB
Cas d'usage : Production (cinéma, VFX, archivage)

Étape 4 : Visualisation (pendant training)¶

Le viewer démarre automatiquement pendant le training :

URL : http://192.168.1.82:7007

Interface :

┌─────────────────────────────────────────────┐
│  [◀] [▶] [▲] [▼]  Camera Controls          │
│                                             │
│  ┌───────────────────────────────────────┐  │
│  │                                       │  │
│  │      [Rendu 3D interactif]           │  │
│  │      - Rotation souris               │  │
│  │      - Zoom molette                  │  │
│  │      - Pan shift+souris              │  │
│  │                                       │  │
│  └───────────────────────────────────────┘  │
│                                             │
│  Training: ████████████░░ 85%               │
│  Step: 850/1000  |  FPS: 45                 │
│  Loss: 0.0124    |  PSNR: 33.2 dB           │
│  ETA: 2min 15s                              │
│                                             │
│  [Export Mesh] [Export Video] [Save]        │
└─────────────────────────────────────────────┘

Étape 5 : Export mesh 3D¶

Quand le training est terminé, exporter le mesh :

cd /opt/nerfstudio

# Trouver le chemin de config
CONFIG=$(ls /data/nerfstudio/outputs/my-scene/nerfacto/*/config.yml | head -1)

# Exporter
./export.sh $CONFIG

Output :

🎨 Exporting mesh from config: /data/nerfstudio/outputs/...
Extracting points: ████████████████ 100%
Generating mesh (Poisson reconstruction)...
Decimating to 50,000 faces...
✅ Mesh exported to: /data/nerfstudio/exports/my-scene.ply

Import in Blender: File → Import → PLY

Formats disponibles : - .ply (point cloud + mesh) - .obj (mesh + textures) - .glb (mesh + textures, web-ready)

Méthodes disponibles¶

Méthode	Qualité	Vitesse	VRAM	Cas d'usage
nerfacto	⭐⭐⭐⭐	15-30 min	8-12 GB	Général (recommandé)
instant-ngp	⭐⭐⭐	5-10 min	4-6 GB	Prototypage rapide
splatfacto	⭐⭐⭐⭐⭐	10-20 min	15-20 GB	Production (meilleure qualité)
mipnerf	⭐⭐⭐⭐	30-60 min	10-14 GB	Scènes multi-échelles
tensorf	⭐⭐⭐	20-40 min	6-10 GB	Scènes larges

Recommandation : - Débuter : nerfacto (bon compromis) - Production : splatfacto (meilleure qualité) - Rapide : instant-ngp (tests, previews)

Cas d'usage¶

1. Reconstruction d'objets (e-commerce, musées)¶

Input : 50-80 photos d'un objet (tournante)

Exemple :

# Photos de chaussure (360°)
mkdir -p /data/nerfstudio/data/shoe/images
cp photos/*.jpg /data/nerfstudio/data/shoe/images/

# Training
cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/shoe splatfacto

# Export pour web viewer
CONFIG=$(ls /data/nerfstudio/outputs/shoe/splatfacto/*/config.yml | head -1)
ns-export gaussian-splat --load-config $CONFIG --output-dir /data/nerfstudio/exports/

Résultat : Viewer 3D interactif pour site web (Three.js, Babylon.js)

2. Numérisation patrimoine (sculptures, monuments)¶

Input : 100-200 photos haute résolution

Exemple :

# Photos de sculpture
mkdir -p /data/nerfstudio/data/sculpture/images
cp photos/*.jpg /data/nerfstudio/data/sculpture/images/

# Training haute qualité
cd /opt/nerfstudio
ns-train splatfacto \
  --data /data/nerfstudio/data/sculpture \
  --output-dir /data/nerfstudio/outputs \
  --viewer.start-viewer true \
  --viewer.host 0.0.0.0 \
  --viewer.port 7007 \
  --pipeline.model.num-samples 512  # Plus de samples = meilleure qualité

# Export mesh haute résolution
CONFIG=$(ls /data/nerfstudio/outputs/sculpture/splatfacto/*/config.yml | head -1)
ns-export poisson \
  --load-config $CONFIG \
  --output-dir /data/nerfstudio/exports \
  --target-num-faces 200000 \  # Mesh très détaillé
  --num-pixels-per-side 4096   # Texture 4K

Résultat : Mesh 3D haute-fidélité pour conservation digitale

3. Visites virtuelles (immobilier, tourisme)¶

Input : 100-150 photos d'une pièce/bâtiment

Exemple :

# Photos d'appartement
mkdir -p /data/nerfstudio/data/apartment/images
cp photos/*.jpg /data/nerfstudio/data/apartment/images/

# Training
cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/apartment nerfacto

# Export vidéo flythrough (visite virtuelle)
CONFIG=$(ls /data/nerfstudio/outputs/apartment/nerfacto/*/config.yml | head -1)
ns-render camera-path \
  --load-config $CONFIG \
  --camera-path-filename /data/nerfstudio/data/apartment/camera_path.json \
  --output-path /data/nerfstudio/exports/apartment-tour.mp4

Résultat : Vidéo 360° haute qualité pour visite virtuelle

4. VFX / Cinéma (assets 3D)¶

Input : Scan volumétrique d'acteurs, décors, props

Exemple :

# Photos d'acteur (tête, 360°)
mkdir -p /data/nerfstudio/data/actor-head/images
cp photos/*.jpg /data/nerfstudio/data/actor-head/images/

# Training ultra-haute qualité (Gaussian Splatting)
cd /opt/nerfstudio
ns-train splatfacto \
  --data /data/nerfstudio/data/actor-head \
  --output-dir /data/nerfstudio/outputs \
  --viewer.start-viewer true \
  --viewer.host 0.0.0.0 \
  --viewer.port 7007 \
  --pipeline.model.num-points 1000000  # 1M points Gaussiens

# Export pour Blender/Unreal Engine
CONFIG=$(ls /data/nerfstudio/outputs/actor-head/splatfacto/*/config.yml | head -1)
ns-export gaussian-splat --load-config $CONFIG --output-dir /data/nerfstudio/exports/

Résultat : Asset 3D photoréaliste pour intégration VFX

Commandes avancées¶

Training personnalisé (full control)¶

ns-train nerfacto \
  --data /data/nerfstudio/data/my-scene \
  --output-dir /data/nerfstudio/outputs \
  --viewer.start-viewer true \
  --viewer.host 0.0.0.0 \
  --viewer.port 7007 \
  --max-num-iterations 30000 \         # Plus d'itérations = meilleure qualité
  --pipeline.datamanager.train-num-rays-per-batch 4096 \  # Plus de rays = plus rapide (si VRAM suffisant)
  --pipeline.model.background-color white \  # Fond blanc (défaut: noir)
  --logging.steps-per-log 10

Export mesh (paramètres avancés)¶

CONFIG=/data/nerfstudio/outputs/my-scene/nerfacto/*/config.yml

# Méthode 1: Poisson (smooth, pour objets fermés)
ns-export poisson \
  --load-config $CONFIG \
  --output-dir /data/nerfstudio/exports \
  --target-num-faces 100000 \  # Nombre de faces (plus = plus détaillé)
  --num-pixels-per-side 2048 \  # Résolution texture
  --normal-method open3d       # Méthode calcul normales

# Méthode 2: Marching Cubes (précis, pour scènes complexes)
ns-export tsdf \
  --load-config $CONFIG \
  --output-dir /data/nerfstudio/exports \
  --resolution 512             # Grille voxel (plus = plus détaillé, mais plus lent)

Export vidéo (flythrough)¶

CONFIG=/data/nerfstudio/outputs/my-scene/nerfacto/*/config.yml

# Méthode 1: Chemin de caméra prédéfini
ns-render camera-path \
  --load-config $CONFIG \
  --camera-path-filename /data/nerfstudio/data/my-scene/camera_path.json \
  --output-path /data/nerfstudio/exports/flythrough.mp4 \
  --rendered-output-names rgb depth \  # Rendu RGB + depth map
  --image-format mp4 \
  --jpeg-quality 100

# Méthode 2: Interpolation entre poses existantes
ns-render interpolate \
  --load-config $CONFIG \
  --pose-source train \  # Utiliser poses du training
  --output-path /data/nerfstudio/exports/interpolated.mp4 \
  --frame-rate 30 \
  --seconds 10

Intégration Homer¶

Nerfstudio est référencé dans le dashboard Homer :

- name: "IA & Machine Learning"
  items:
    - name: "Nerfstudio"
      logo: "assets/tools/nerfstudio.png"
      subtitle: "Neural Radiance Fields - 3D reconstruction"
      url: "http://192.168.1.82:7007"

Accès depuis Homer : http://192.168.1.82:8080

Troubleshooting¶

Training très lent¶

# Vérifier utilisation GPU
nvidia-smi

# Si utilisation faible (~10%) :
# → Augmenter num-rays-per-batch (si VRAM disponible)
ns-train nerfacto \
  --data /data/nerfstudio/data/my-scene \
  --pipeline.datamanager.train-num-rays-per-batch 8192  # Défaut: 4096

# Si CUDA out of memory :
# → Réduire num-rays-per-batch
ns-train nerfacto \
  --data /data/nerfstudio/data/my-scene \
  --pipeline.datamanager.train-num-rays-per-batch 2048

COLMAP échoue (poses caméra)¶

Si COLMAP ne parvient pas à calculer les poses :

# Vérifier que photos ont EXIF (metadata caméra)
exiftool /data/nerfstudio/data/my-scene/images/*.jpg | grep "Focal Length"

# Si pas d'EXIF, spécifier manuellement :
ns-process-data images \
  --data /data/nerfstudio/data/my-scene/images \
  --output-dir /data/nerfstudio/data/my-scene \
  --camera-type perspective \
  --matching-method exhaustive  # Plus lent mais plus robuste

Erreurs communes : - Photos trop floues → COLMAP échoue (reprendre photos nettes) - Éclairage variable → Mauvaises correspondances (éclairage stable requis) - Trop peu de photos (< 30) → Poses instables (minimum 50 photos)

Résultat flou ou bruité¶

# Augmenter nombre d'itérations
ns-train nerfacto \
  --data /data/nerfstudio/data/my-scene \
  --max-num-iterations 50000  # Défaut: 30000

# Passer à une méthode plus précise
cd /opt/nerfstudio
./train.sh /data/nerfstudio/data/my-scene splatfacto

Viewer ne charge pas¶

# Vérifier que service tourne
sudo systemctl status nerfstudio

# Vérifier logs
sudo journalctl -u nerfstudio -n 50

# Redémarrer viewer
sudo systemctl restart nerfstudio

# Tester manuellement
cd /opt/nerfstudio
python3 -m nerfstudio.scripts.viewer.run_viewer --host 0.0.0.0 --port 7007

Export mesh vide¶

# Vérifier que training est terminé (loss < 0.01)
# Si training incomplet, continuer :
ns-train nerfacto \
  --data /data/nerfstudio/data/my-scene \
  --load-dir /data/nerfstudio/outputs/my-scene/nerfacto/TIMESTAMP \  # Reprendre training
  --max-num-iterations 50000

# Essayer méthode d'export alternative
CONFIG=/data/nerfstudio/outputs/my-scene/nerfacto/*/config.yml
ns-export tsdf --load-config $CONFIG --output-dir /data/nerfstudio/exports

Maintenance¶

Nettoyage outputs anciens¶

# Supprimer outputs > 30 jours
find /data/nerfstudio/outputs -type d -mtime +30 -exec rm -rf {} \;

# Vérifier espace disque
du -sh /data/nerfstudio/*

Mise à jour Nerfstudio¶

# Pull dernière version
sudo pip3 install --upgrade nerfstudio

# Redémarrer service
sudo systemctl restart nerfstudio

# Vérifier version
python3 -c "import nerfstudio; print(nerfstudio.__version__)"

Sauvegarde projets¶

# Sauvegarder un projet complet
sudo tar czf /tmp/nerfstudio-my-scene-$(date +%Y%m%d).tar.gz \
  /data/nerfstudio/data/my-scene \
  /data/nerfstudio/outputs/my-scene

# Copier sur NAS
cp /tmp/nerfstudio-*.tar.gz /mnt/nas/backups/

Ressources¶

Documentation officielle : https://docs.nerf.studio
GitHub : https://github.com/nerfstudio-project/nerfstudio
Discord : https://discord.gg/RFSHkYuD4v
Paper : https://arxiv.org/abs/2302.04264

Résumé des ports¶

Service	Port	Protocole	Accès
Nerfstudio Viewer	7007	HTTP	LAN uniquement

Comparaison avec alternatives¶

Solution	Qualité	Vitesse	Coût	Facilité
Nerfstudio (RTX 5090)	⭐⭐⭐⭐⭐	10-30 min	Gratuit	Moyenne
Polycam	⭐⭐⭐⭐	5-10 min	$20/mois	Facile
RealityCapture	⭐⭐⭐⭐	30-60 min	$99/mois	Moyenne
Meshroom	⭐⭐⭐	60-120 min	Gratuit	Difficile
Luma AI	⭐⭐⭐⭐	10-20 min	$29/mois	Très facile

Avantages Nerfstudio : - ✅ Gratuit et open-source - ✅ Meilleure qualité (Gaussian Splatting) - ✅ Contrôle total (paramètres, exports) - ✅ Données privées (RGPD compliant) - ✅ GPU local (RTX 5090) = très rapide

Avantages cloud : - ✅ Pas de gestion infrastructure - ✅ Interface plus simple - ✅ Mobile app (scan avec smartphone)