Skip to content

AGENTS.md

Latest commit

 

History

History
115 lines (94 loc) · 5.41 KB

AGENTS.md

File metadata and controls

115 lines (94 loc) · 5.41 KB
Raw

RenderPOC

Banc d'essai de reconstruction 3D d'objet. Une vidéo d'orbite entre, un mesh + un fichier de métriques sortent. L'objectif du POC est de comparer plusieurs approches de reconstruction sur la même entrée, pas de livrer un produit.

Stack : Python 3.11, uv, OpenCV, Open3D, trimesh, PyQt6 (GUI de bench). Les modèles de reconstruction ne sont pas des dépendances de ce paquet : ce sont des sous-processus isolés (voir docs/backend-contract.md).

Quick start

.\make.ps1 setup     # env racine (aucune dependance GPU)
.\make.ps1 check     # ruff + pytest — DOIT passer sans GPU
.\make.ps1 envs      # envs backends GPU (da3, mapanything) — long, telecharge torch
.\make.ps1 gui       # GUI de benchmark

Pipeline complet sur une vidéo, inférence sur GPU loué :

uv run renderpoc gpu --backends all --datacenter EU-RO-1   # que louer, maintenant
uv run renderpoc remote configure --ssh "ssh root@... -p ... -i ..." --price 0.44
uv run renderpoc remote provision --envs da3,mapanything,colmap   # une seule fois
uv run renderpoc run data\piece.mp4 --backends all --remote --square-size-mm 24.7
uv run renderpoc runs                      # liste les runs

Avant la première acquisition, fabriquer le damier — c'est la seule source d'échelle métrique du projet :

uv run renderpoc checkerboard --out board.svg    # SVG cote en mm, imprimer a 100 %

Étape par étape (chaque étape est rejouable seule) :

uv run renderpoc frames data\piece.mp4          # -> runs/<id>/frames/{sparse,dense}
uv run renderpoc geom --run <id> --backend da3  # -> runs/<id>/stages/geom_da3
uv run renderpoc fuse --run <id>                # -> runs/<id>/final/mesh.glb
uv run renderpoc eval --run <id>                # -> runs/<id>/metrics.json

Contraintes globales

  1. MUST NOT : aucun import torch, open_clip, transformers ou dépendance CUDA dans src/renderpoc/. Les modèles tournent en sous-processus. C'est l'invariant qui rend ce dépôt installable et testable sans GPU.
  2. MUST : tout backend communique par request.json / result.json (docs/backend-contract.md). Pas d'autre canal.
  3. MUST : toute écriture sur disque se fait sous runs/<run_id>/. Rien en dehors.
  4. MUST NOT : la GUI ne calcule aucune métrique et ne charge aucun modèle. Elle lit manifest.json et metrics.json. Si une valeur manque à l'écran, le bug est en amont.
  5. MUST : un backend déclare un besoin (min_vram_mb), jamais une machine. Le runner refuse de le lancer sur une carte trop petite, marge de 2 Go comprise. L'inférence se fait sur GPU loué (--remote) ; le poste local orchestre. Voir docs/compute-budget.md et docs/remote-execution.md.
  6. MUST : .\make.ps1 check passe sans GPU, sans poids téléchargés, sans réseau.
  7. MUST NOT : ne jamais mocker un modèle réel dans les tests. Les backends réels se vérifient par les commandes de vérification de docs/features.md (F05, F06).
  8. MUST : une feature ne passe à passing dans docs/features.md que si sa commande de vérification a réellement été exécutée avec succès. Reporter le hash de commit ou la sortie dans le champ evidence.
  9. MUST : mettre à jour PROGRESS.md avant de terminer une session.
  10. MUST NOT : pas de nouvelle dépendance dans l'env racine sans nécessité. C'est un POC ; la surface doit rester petite.
  11. MUST : les artefacts lourds (runs/, weights/, data/, vidéos) restent hors git.
  12. MUST : toute unité de longueur exposée est le mètre en interne, le millimètre à l'affichage. L'échelle métrique vient du damier (src/renderpoc/eval/scale.py).

Documents à consulter

Document Quand le lire
docs/backend-contract.md Obligatoire avant d'ajouter ou de modifier un backend
docs/features.md Au début de chaque session : quoi faire ensuite, et comment le vérifier
docs/remote-execution.md Pour louer un GPU, provisionner le volume, lancer un run distant
docs/compute-budget.md Besoins VRAM mesurés, prix des cartes, licences, accès aux poids
docs/acquisition-protocol.md Avant de filmer, ou pour diagnostiquer une mauvaise reconstruction
docs/metrics.md Pour interpréter metrics.json ou ajouter une métrique
docs/pipeline-explique.md Vulgarisation : ce que fait chaque étape et pourquoi
src/renderpoc/backends/ARCHITECTURE.md Pour comprendre le registre et le runner

Structure

src/renderpoc/
  core/       run id, manifeste, arborescence d'un run, config, logging
  keyframes/  decodage video, score de nettete, selection sparse/dense/holdout
  backends/   contrat, runner subprocess, registre, adaptateurs
  geometry/   fusion depth+poses -> mesh, decoupe de la piece, export GLB
  eval/       calibration damier, metriques, ecriture de metrics.json
  remote/     catalogue GPU, transport ssh/scp, execution distante
  gui/        PyQt6, lecteur de runs
envs/         un projet uv par backend lourd (lockfiles separes) + provision.sh
runs/         artefacts d'execution (gitignore)

Vérification

.\make.ps1 lint     # ruff check + format --check
.\make.ps1 test     # pytest
.\make.ps1 check    # les deux

Le pipeline complet se vérifie de bout en bout avec le backend fake, sans GPU :

uv run renderpoc run tests\assets\synth.mp4 --backends fake