NV-Generate-CT (rflow-ct)

Purpose

• Utilisé pour générer des volumes et des masques CT synthétiques avec NV-Generate-CTMR rflow-ct. À ne pas utiliser pour les données d'entraînement en production sans examen.
• Utiliser le wrapper exactement tel que documenté ; ne pas remplacer le point d'entrée upstream avec une implémentation manuscrite.
• Ne pas écrire de code d'inférence personnalisé pour les exécutions normales. Le wrapper gère la mise en scène de la configuration, les chemins de sortie, la preuve de mappage des étiquettes et la validation.
• Manifest I/O : les entrées sont config_infer_override ; les sorties sont synthetic_ct_volumes et result_json.

Instructions

• Lire skill_manifest.yaml avant de modifier les arguments, les effets secondaires ou les portes de validation.
• Exécuter scripts/run_rflow_ct.py via la commande documentée ci-dessous ; garder les sorties sous un répertoire d'exécution fourni par l'appelant.
• Si un agent hôte expose run_script, utiliser run_script("scripts/run_rflow_ct.py", args=[...]); sinon exécuter la commande Bash/Python affichée ci-dessous.
• Emettre un seul bloc de code bash et garder l'étape python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" dans la même commande — l'environnement d'exécution peut être un environnement frais sans nibabel/MONAI, donc supprimer l'installation échoue avec ModuleNotFoundError.
• Ne pas ajouter rm, mkdir ou tout nettoyage de --output-dir ; le wrapper le crée. Utiliser un --output-dir frais au lieu de supprimer un existant.
• Vérifier le JSON émis et les conseils du vérificateur associé avant de traiter l'exécution comme une preuve.

Scripts disponibles

Prérequis

• Variables d'environnement requises : NV_GENERATE_ROOT.
• Exigences d'exécution : GPU/CUDA lorsque déclaré par le manifest ; packages Python listés dans runtime.side_effects.pip_packages.
• Effets secondaires : écrit les sorties générées sous le --output-dir de l'appelant, peut mettre en cache les assets du modèle sous ~/.cache/huggingface/, et peut contacter https://huggingface.co ou https://github.com pendant la configuration.
• Exécuter les commandes depuis la racine du repository sauf si une section existante ci-dessous le dit autrement.

Limitations

• C'est un wrapper léger. L'inférence, l'échantillonnage et le décodage sont entièrement délégués à scripts.inference de NVIDIA-Medtech/NV-Generate-CTMR. Ne pas modifier le code sous $NV_GENERATE_ROOT.
• rflow-ct requiert CUDA et ≈ 16 GB de VRAM minimum pour la taille de sortie par défaut 256³. Une taille de sortie plus grande (par exemple 512×512×768) nécessite un A100/H100.
• Les volumes de sortie sont synthétiques. Ils ne sont pas sûrs à utiliser comme données d'entraînement pour les modèles medtech de production sans un examen de qualité indépendant.
• Pas pour le déploiement clinique, l'interprétation clinique, le diagnostic autonome ou la soumission réglementaire.

Dépannage

Encapsule le pipeline de synthèse de rectified-flow en amont NVIDIA-Medtech/NV-Generate-CTMR. Le wrapper ne réimplémente pas la diffusion, l'échantillonnage ou le décodage de l'autoencodeur — il exécute le point d'entrée upstream scripts.inference exactement tel que la documentation du projet le présente et inspecte les paires image/masque produites.

Conditions préalables

1. Cloner le repo upstream et pointer NV_GENERATE_ROOT dessus (une fois) :

   test -d "$HOME/nv-generate-ctmr/.git" || \
     git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git $HOME/nv-generate-ctmr
   export NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
   pip install -r "$NV_GENERATE_ROOT/requirements.txt"

2. Télécharger les poids rflow-ct et les datasets de candidats de masques dans le clone (une fois, ≈ 5,5 GB) :

   cd "$NV_GENERATE_ROOT"
   python -m scripts.download_model_data --version rflow-ct --root_dir "./"

   Les candidats de masques (datasets/all_masks_flexible_size_and_spacing_4000) conditionnent l'échantillonneur de diffusion ; les omettre via --model_only rendra le script d'inférence échouer avec une erreur de fichier manquant au démarrage. Le fichier de condition de taille anatomique fait également partie du téléchargement CT complet et est nécessaire pour la génération de masques contrôlables.

3. GPU NVIDIA avec ≥ 16 GB de VRAM et CUDA. Il n'y a pas de fallback CPU.

Pour les commandes d'exécution générées par agent, préférer la commande de wrapper courte dans Utilisation. Ne pas ajouter les étapes de configuration de clone ou de téléchargement de modèle lorsque NV_GENERATE_ROOT ou le cache upstream local du repo est déjà présent. Dans un environnement Python frais, inclure quand même pip install -r "$NV_GENERATE_ROOT/requirements.txt" avant le wrapper sauf si l'environnement actif a déjà prouvé que ces imports sont disponibles ; les poids mis en cache n'impliquent pas les packages Python mis en cache. Exécuter le wrapper depuis la racine du repository medical-AI-skills. Si la configuration requiert cd "$NV_GENERATE_ROOT", revenir au repository Medical AI Skills avant d'invoquer skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py.

Utilisation

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/nv-generate-ctmr}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
  PATH_TO_CONFIG_INFER.json \
  --output-dir runs/nv_generate_ct_rflow_demo \
  --random-seed 0 \
  --version rflow-ct

Remplacer PATH_TO_CONFIG_INFER.json par le chemin de requête/configuration réel de l'utilisateur. Ne pas copier le chemin du fixture de ce document sauf si l'utilisateur a explicitement demandé l'exécution de ce fixture. Si l'utilisateur dit « la requête de cas se trouve à runs/.../chest_lung_tumor_controllable.json », ce chemin exact est le premier argument positionnel de scripts/run_rflow_ct.py.

L'argument du fixture est un fichier override config_infer.json : il peut remplacer num_output_samples, body_region, anatomy_list, controllable_anatomy_size, output_size et spacing. Passer default pour utiliser la configuration upstream en l'état. Le wrapper met en scène l'override dans l'arborescence upstream avant l'exécution.

Catalogue de fixtures

fixtures/ contient des configurations curées pour les cas d'usage communs de synthèse appariée : lobes pulmonaires thoraciques, thorax avec tumeur pulmonaire contrôlable, organes solides abdominaux, abdomen avec tumeur hépatique contrôlable, tête + colonne cervicale, pelvis. Voir fixtures/README.md pour la table complète.

Commandes d'aide

# Parcourir le label_dict à 132 classes groupé par région corporelle.
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --region chest
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --controllable
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --filter tumor

# Valider un fixture et prévisualiser le coût sans lancer l'inférence.
NV_GENERATE_ROOT=$HOME/nv-generate-ctmr \
  python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
    skills/nv-generate-ct-rflow/fixtures/abdomen_liver_spleen.json \
    --output-dir runs/preview --preflight-only

Les aides avancées restent à l'intérieur de cette skill pour le débogage et les modes de génération CT moins courants. Les utiliser uniquement lorsque l'utilisateur demande explicitement ce mode :

# Diagnostic de masque MAISI brut, utile pour vérifier poumon tumeur -> étiquette 23.
python skills/nv-generate-ct-rflow/scripts/run_ct_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_mask_lung_tumor.json \
  --output-dir runs/ct_mask_debug --preflight-only

# Image CT à partir d'un masque d'étiquette MAISI existant avec étiquette de corps 200.
python skills/nv-generate-ct-rflow/scripts/run_ct_from_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_from_mask_request_example.json \
  --output-dir runs/ct_from_mask_demo

# Génération d'images CT seules sans étiquettes appariées.
python skills/nv-generate-ct-rflow/scripts/run_ct_image.py \
  skills/nv-generate-ct-rflow/fixtures/ct_image_only_default.json \
  --output-dir runs/ct_image_only_demo --version rflow-ct

Le wrapper exécute la vérification préalable à chaque invocation (indépendamment de --preflight-only) : limites de schéma de configuration, noms d'anatomie appariés à la label_dict upstream, body_region dans l'ensemble pris en charge, contraintes de controllable_anatomy_size, contrats de taille de sortie/espacement CT upstream, minimums de FOV x/y conscients de la région corporelle, présence de dataset sous $NV_GENERATE_ROOT/datasets/, CUDA disponible et un VRAM de pointe/temps mural estimé. Les exécutions estimées dépasser 5 min de temps mural ou 30 GB de pointe VRAM requièrent --yes pour procéder.

Chaque invocation exécute python -m scripts.inference -t configs/config_network_rflow.json -i configs/config_infer.json -e configs/environment_rflow-ct.json --random-seed <s> --version rflow-ct. Les preuves de sortie enregistrent le commit git upstream, les hashes de checkpoint du modèle, la configuration rendue, la géométrie image/masque par échantillon, l'ensemble d'étiquettes de masque, le résumé de plage HU d'image et les volumes de voxels par classe.

Lorsque controllable_anatomy_size est non vide, l'upstream ignore la anatomy_list plus large pour la carte d'étiquette appariée sauvegardée et filtre les étiquettes aux noms d'anatomie contrôlables. Les valeurs d'étiquette appariées sauvegardées sont des ordinaux locaux 1..N, pas des ID d'étiquette MAISI brutes. Lire output.output_label_mapping dans result_json pour mapper les étiquettes de sortie sauvegardées vers les étiquettes sources ; par exemple, l'étiquette de sortie 1 peut représenter l'étiquette MAISI 23 (lung tumor). Pour les exemples curés de tumeur pulmonaire, préférer une taille contrôlable autour de 0,5 ou plus grande ; les demandes plus petites comme 0,2 peuvent produire des composants d'étiquette-23 absents ou extrêmement petits pour certaines graines.

Pour les détails de FOV et de configuration, voir references/fov-and-downloads.md. Pour les détails de l'espace d'étiquette d'aide avancée, voir references/ct-mask-label-space.md et references/ct-from-mask-format.md.

Carte d'exemple visuelle

À côté des paires NIfTI, le wrapper écrit summary.html dans le répertoire de sortie : un triptyque de tranche médiane par échantillon (axial / coronal / sagittal) avec superposition d'étiquette, plus un tableau de la configuration rendue et des agrégats orientés vérificateur. Vous permet de jeter un coup d'œil au résultat sans ouvrir 3D Slicer. Passer --no-summary-card pour ignorer.

La plausibilité anatomique (sanité de l'ensemble d'étiquettes, plage HU de voxels comme CT, correspondance de géométrie image/masque, étiquettes de sortie déclarées présentes, plancher HU du lobe pulmonaire) est vérifiée par verifiers/ct_synthesis_quality_v1.

Pas pour l'interprétation clinique, les données d'entraînement pour le déploiement en production ou tout usage autre que la recherche synthétique.