nv-generate-ct-rflow

NV-Generate-CT（rflow-ct）

目的

• NV-Generate-CTMR rflow-ct を使用して、合成 CT ボリュームとマスクを生成します。レビューなしで本番環境のトレーニングデータに使用しないでください。
• ラッパーはドキュメントに記載されたとおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• 通常の実行では、カスタム推論コードを作成しないでください。設定のステージング、出力パス、ラベルマッピングの根拠、および検証はラッパーが管理します。
• マニフェスト I/O：入力は config_infer_override、出力は synthetic_ct_volumes と result_json です。

手順

• 引数、副作用、または検証ゲートを変更する前に、skill_manifest.yaml を読んでください。
• 以下に記載されたコマンドを使用して scripts/run_rflow_ct.py を実行してください。出力は呼び出し元から指定された実行ディレクトリの下に保持してください。
• ホストエージェントで run_script を利用できる場合は、run_script("scripts/run_rflow_ct.py", args=[...]) を使用してください。それ以外の場合は、以下に示す Bash/Python コマンドを実行してください。
• 単一の bash コードブロックを出力し、python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" の手順を同じコマンド内に含めてください。実行環境が nibabel／MONAI のない新規環境の場合があるため、インストールを省略すると ModuleNotFoundError が発生します。
• rm、mkdir、または --output-dir のクリーンアップを追加しないでください。ラッパーが出力ディレクトリを作成します。既存のディレクトリを削除する代わりに、新しい --output-dir を使用してください。
• 実行結果を根拠として扱う前に、出力された JSON と、対応する検証ガイダンスを確認してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/_anatomy.py	主エントリーポイントで使用される内部ヘルパーです。	インポート専用。直接呼び出さないでください。
scripts/_summary_card.py	主エントリーポイントで使用される内部ヘルパーです。	インポート専用。直接呼び出さないでください。
scripts/list_anatomies.py	カタログまたは解剖部位の検索に使用するヘルパーコマンドです。	[--region REGION] [--filter TEXT] [--controllable]
scripts/run_rflow_ct.py	skill_manifest.yaml で宣言された主エントリーポイントです。	CONFIG_INFER.json --output-dir OUT_DIR [--random-seed N] [--version rflow-ct] [--yes]
scripts/run_ct_mask.py	スタンドアロンの raw MAISI マスク生成に使用する、高度な診断ヘルパーです。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--preflight-only] [--yes]
scripts/run_ct_from_mask.py	MAISI ラベルマスクから CT 画像を生成するための高度なヘルパーです。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--yes]
scripts/run_ct_image.py	対応するラベルなしで CT 画像のみを生成するための高度なヘルパーです。	MODEL_CONFIG.json --output-dir OUT_DIR [--version rflow-ct] [--random-seed N] [--yes]

前提条件

• 必須の環境変数：NV_GENERATE_ROOT。
• 実行時の要件：マニフェストで宣言されている場合は GPU/CUDA、runtime.side_effects.pip_packages に記載された Python パッケージ。
• 副作用：生成した出力を呼び出し元の --output-dir の下に書き込みます。モデルアセットを ~/.cache/huggingface/ にキャッシュする場合があり、セットアップ中に https://huggingface.co または https://github.com に接続する場合があります。
• 以下の既存のセクションで別途指定されていない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。推論、サンプリング、デコードはすべて NVIDIA-Medtech/NV-Generate-CTMR の scripts.inference に委譲されます。$NV_GENERATE_ROOT の下にあるコードを変更しないでください。
• rflow-ct には CUDA が必要であり、デフォルトの 256³ output_size では最低でも約 16 GB の VRAM が必要です。より大きな output_size（例：512×512×768）には A100/H100 が必要です。
• 出力ボリュームは合成データです。独立した品質レビューなしで、本番環境の医療技術モデルのトレーニングデータとして使用しないでください。
• 臨床導入、臨床的解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係の不足またはインポートエラー	skill_manifest.yaml と実行時パッケージに差異があります。	マニフェストで宣言されているパッケージをインストールするか、ドキュメントに記載されているセットアップコマンドを使用してください。
出力が空、またはスキーマが無効	入力パスの誤り、未対応のモダリティ、または上流処理の失敗です。	既知のフィクスチャで再実行し、ラッパーの JSON と標準エラー出力を確認してください。
検証ゲートの失敗	出力が宣言されたエンジニアリング上の不変条件に違反しました。	失敗時のエビデンスパックを保持し、ゲートのメッセージを参考に入力またはラッパーコードを修正してください。

上流の NVIDIA-Medtech/NV-Generate-CTMR 整流フロー合成パイプラインをラップしています。ラッパーは拡散処理、 サンプリング、またはオートエンコーダーによるデコードを再実装しません。 プロジェクトの README に記載されたとおり、上流の scripts.inference エントリーポイントをシェルから実行し、 生成された画像とマスクのペアを検査します。

前提条件

1. NV_GENERATE_ROOT がローカルのチェックアウトをすでに指している場合、ラッパーはそれを使用し、 現在のコミットを結果に記録します。それ以外の場合は、推奨される固定バージョンのデフォルトのチェックアウトを 作成してください（初回のみ）。

   if [ -z "${NV_GENERATE_ROOT:-}" ]; then
     export NV_GENERATE_COMMIT=61c4ec709b84cad468852243c48e250bec732074
     export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7"
     if [ ! -d "$NV_GENERATE_ROOT/.git" ]; then
       git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git "$NV_GENERATE_ROOT"
       git -C "$NV_GENERATE_ROOT" checkout --detach "$NV_GENERATE_COMMIT"
     fi
   fi
   python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt"
   

2. rflow-ct の重みおよびマスク候補データセットを クローン内にダウンロードしてください（初回のみ、約 5.5 GB）。

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

   マスク候補（datasets/all_masks_flexible_size_and_spacing_4000）は拡散サンプラーの 条件付けに使用されます。--model_only で省略すると、 起動時に推論スクリプトがファイル不足エラーで失敗します。 解剖学的サイズの条件ファイルも CT 一式のダウンロードに含まれており、 制御可能なマスク生成に必要です。

3. 16 GB 以上の VRAM と CUDA を備えた NVIDIA GPU が必要です。CPU での代替実行には対応していません。

エージェントが生成するユーザー向け実行コマンドでは、「使用方法」に記載された 短いラッパーコマンドを優先してください。NV_GENERATE_ROOT またはリポジトリ内の上流キャッシュが すでに存在する場合は、クローンやモデルのダウンロード手順を先頭に追加しないでください。新しい Python 環境では、対象環境で必要なインポートが利用可能であることがすでに確認されている場合を除き、ラッパーの前に python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" を含めてください。重みがキャッシュされていても、 Python パッケージがキャッシュされているとは限りません。ラッパーは medical-AI-skills リポジトリのルートから実行してください。セットアップのために cd "$NV_GENERATE_ROOT" が必要な場合は、skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py を実行する前に Medical AI Skills リポジトリに戻ってください。

使用方法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
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

PATH_TO_CONFIG_INFER.json を、ユーザーが指定した実際のリクエスト／設定ファイルの パスに置き換えてください。ユーザーから明示的にそのフィクスチャの実行を求められない限り、 このドキュメントに記載されたフィクスチャのパスをコピーしないでください。ユーザーが「ケースのリクエストは runs/.../chest_lung_tumor_controllable.json にあります」と伝えた場合、この正確なパスを scripts/run_rflow_ct.py の最初の位置引数に指定してください。

フィクスチャ引数は config_infer.json のオーバーライドファイルです。num_output_samples、body_region、 anatomy_list、controllable_anatomy_size、output_size、spacing を置き換えられます。上流の設定を そのまま使用するには default を指定してください。ラッパーは実行前に、オーバーライドを上流ツリーに ステージングします。

フィクスチャカタログ

fixtures/ には、一般的なペア合成の用途に対応する、厳選された設定が含まれています。胸部の 肺葉、制御可能な肺腫瘍を含む胸部、腹部の実質臓器、制御可能な肝腫瘍を含む腹部、 頭部と頸椎、骨盤が用意されています。全表については fixtures/README.md を参照してください。

ヘルパーコマンド

# Browse the 132-class label_dict grouped by body region.
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

# Validate a fixture and preview cost without launching inference.
NV_GENERATE_ROOT=$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7 \
  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

高度なヘルパーは、このスキル内でデバッグやあまり一般的でないCT生成モードに使用します。ユーザーがそのモードを明示的に求めた場合にのみ使用してください。

# Raw MAISI mask diagnostic, useful for checking lung tumor -> label 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

# CT image from an existing MAISI label mask with body label 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

# CT image-only generation without paired labels.
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

ラッパーは呼び出しのたびに（--preflight-only の指定にかかわらず）事前チェックを実行します。チェック項目は、設定スキーマの制約、上流の label_dict と照合した解剖学的名称、サポートされる値の集合に含まれる body_region、controllable_anatomy_size の制約、上流のCT出力サイズと間隔の仕様、体の部位を考慮した x/y FOV の最小値、$NV_GENERATE_ROOT/datasets/ 配下のデータセットの有無、CUDA が利用可能であること、推定ピークVRAM／実行時間です。推定実行時間が5分、またはピークVRAMが30 GBを超える実行を続行するには、--yes が必要です。

呼び出しのたびに 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 を実行します。出力エビデンスには、上流の git コミット、モデルチェックポイントのハッシュ、レンダリングされた設定、サンプルごとの画像／マスクのジオメトリ、マスクのラベル集合、画像のHU範囲の概要、クラスごとのボクセル体積が記録されます。

controllable_anatomy_size が空でない場合、上流は保存されるペアのラベルマップに対して、より広範な anatomy_list を無視し、ラベルを制御対象の解剖学的名称に絞り込みます。保存されるペアのラベル値はローカルの 1..N の序数であり、元の MAISI ラベルIDではありません。保存された出力ラベルを元のラベルに対応付けるには、result_json の output.output_label_mapping を参照してください。たとえば、出力ラベル 1 は MAISI ラベル 23（lung tumor）を表す場合があります。 キュレーション済みの肺腫瘍の例では、制御可能なサイズをおよそ 0.5 以上にすることをおすすめします。0.2 などの小さな値を指定すると、シードによってはラベル23の成分が存在しないか、非常に小さくなることがあります。

FOV とセットアップの詳細については、references/fov-and-downloads.md を参照してください。高度なヘルパーのラベル空間の詳細については、references/ct-mask-label-space.md と references/ct-from-mask-format.md を参照してください。

ビジュアルサンプルカード

NIfTI のペアとともに、ラッパーは出力ディレクトリに summary.html を書き込みます。サンプルごとの中央スライスの三方向表示（軸位／冠状断／矢状断）にラベルを重ねて表示し、レンダリングされた設定と検証用の集計値を表にまとめます。3D Slicer を起動せずに結果を目視で確認できます。スキップするには --no-summary-card を渡してください。

解剖学的な妥当性（ラベル集合の整合性、CTとしてのボクセルHU範囲、画像／マスクのジオメトリの一致、宣言された出力ラベルの存在、肺葉のHU下限）は、verifiers/ct_synthesis_quality_v1 によってチェックされます。

臨床的な解釈、本番環境への展開に使用する学習データ、または合成研究以外の用途には使用しないでください。