nv-segment-ctmr

NV-Segment-CTMR

目的

• CT または MRI の NIfTI ボリュームに対して NV-Segment-CTMR を実行し、ラベルマップの証拠を記録するために使用します。臨床的な解釈には使用しません。
• ラッパーはドキュメントに記載されたとおりに使用してください。アップストリームのエントリーポイントを手書きの実装に置き換えないでください。
• マニフェストの入出力：入力は ct_or_mr_volume、出力は label_map と result_json です。

手順

• 引数、副作用、検証ゲートを変更する前に、skill_manifest.yaml を確認してください。
• 下記に記載されたコマンドを使って scripts/run_ctmr.py を実行し、出力は呼び出し元が指定した実行ディレクトリ内に保持してください。
• ホストエージェントが run_script を提供している場合は、run_script("scripts/run_ctmr.py", args=[...]) を使用してください。それ以外の場合は、下記の Bash／Python コマンドを実行してください。
• 実行結果を証拠として扱う前に、出力された JSON と、対応する検証ガイダンスを確認してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/run_ctmr.py	skill_manifest.yaml で宣言されている主要なエントリーポイントです。	PATH_TO_IMAGE.nii.gz --output-dir OUT_DIR --modality CT_BODY [--label-prompts IDS]

前提条件

• 実行要件：マニフェストで指定されている場合は GPU／CUDA が必要です。Python パッケージは runtime.side_effects.pip_packages に記載されています。
• 任意の環境変数：NV_SEGMENT_CTMR_ROOT は信頼できるアップストリームのチェックアウト先を指定します。CUDA_VISIBLE_DEVICES は利用可能な GPU を制限します。MONAI_DATA_DIRECTORY と PYTORCH_CUDA_ALLOC_CONF は、必要に応じてラッパーの出力先ローカルキャッシュとアロケーターのデフォルト設定を上書きします。
• 副作用：呼び出し元の --output-dir 配下にセグメンテーション出力を書き込みます。モデルアセットを ~/.cache/huggingface/ 配下にキャッシュする場合があり、セットアップ中に https://github.com または https://huggingface.co にアクセスする場合があります。
• 下記の既存セクションで別途指定されていない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。推論、前処理、後処理はすべて、$NV_SEGMENT_CTMR_ROOT 配下のアップストリーム MONAI バンドル、またはリポジトリ内のフォールバック先 .workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR に委ねられます。
• ラッパーのデフォルト経路では、CT_BODY、MRI_BODY、または MRI_BRAIN に対して「すべてをセグメント化する」自動推論を実行します。MRI_BRAIN の入力は、アップストリームの脳前処理要件にあらかじめ従っている必要があります。
• ラベル名は、利用可能な場合、アップストリームの設定から読み込まれます。ラベル辞書がない場合でも、ラッパーはラベル ID を記録し、負の ID のみを無効として扱います。
• 臨床、診断、規制、治療計画に関する主張はありません。
• 臨床での導入、臨床的な解釈、自律的な診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係の欠落またはインポートエラー	skill_manifest.yaml に記載された実行時パッケージとの不整合です。	マニフェストで宣言されているパッケージをインストールするか、ドキュメントに記載されたセットアップコマンドを使用してください。
出力が空、またはスキーマが無効	入力パスが誤っている、モダリティがサポートされていない、またはアップストリームでエラーが発生しています。	既知のフィクスチャを使って再実行し、ラッパーの JSON と stderr を確認してください。
検証ゲートの失敗	出力が宣言済みのエンジニアリング不変条件に違反しています。	失敗した証拠パックを保持し、ゲートのメッセージを参考に入力またはラッパーコードを修正してください。

アップストリームの NVIDIA-Medtech/NV-Segment-CTMR CT／MRI セグメンテーションバンドルをラップします。ラッパーは VISTA3D の 推論を再実装しません。ドキュメントに記載された python -m monai.bundle run エントリーポイントをシェル経由で実行し、生成された NIfTI ラベルマップを検査します。

正確に実行可能なコマンド形式

CT 身体部位セグメンテーションのユーザー実行およびベンチマークの回答では、新しい環境でも使用できる、次のリポジトリルートでのコマンド形式をそのまま使用してください。

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz --modality CT_BODY --output-dir OUT_DIR

python -m nv_segment_ctmr、infer.py、Medical AI Skills run のコマンドを作らないでください。PATH_TO_IMAGE.nii.gz には、ユーザーが指定した入力パスを使用する必要があります。 ベンチマークまたはユーザー実行の回答では、bash ブロックに mkdir -p .workbench_data/upstreams、git clone、mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"、 hf download、mv "$NV_SEGMENT_CTMR_ROOT/...、または共有 upstream チェックアウト内にファイルを作成、ダウンロード、移動するその他のコマンドが含まれている場合、そのブロックは無効です。

前提条件

メンテナーによる初回セットアップ専用です。これらのコマンドをユーザー向けの回答やベンチマーク用コマンドに含めないでください。 ベンチマーク環境には、リポジトリ内の upstream キャッシュとモデルファイルがすでに用意されています。

NV_SEGMENT_CTMR_ROOT がローカルのバンドルのチェックアウト先をすでに指している場合、ラッパーはそれを使用し、結果に現在のコミットを記録します。それ以外の場合は、推奨される固定バージョンのデフォルトを一度だけクローンします。

if [ -z "${NV_SEGMENT_CTMR_ROOT:-}" ]; then
  export NV_SEGMENT_CTMR_COMMIT=cb921f5c58837c0f42a713855d68b32af88e1cdd
  export NV_SEGMENT_CTMR_CHECKOUT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5"
  if [ ! -d "$NV_SEGMENT_CTMR_CHECKOUT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git "$NV_SEGMENT_CTMR_CHECKOUT"
    git -C "$NV_SEGMENT_CTMR_CHECKOUT" checkout --detach "$NV_SEGMENT_CTMR_COMMIT"
  fi
  export NV_SEGMENT_CTMR_ROOT="$NV_SEGMENT_CTMR_CHECKOUT/NV-Segment-CTMR"
fi
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python -c "import monai, nibabel, numpy"

mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  hf download nvidia/NV-Segment-CTMR \
    --revision 4fb8b4a6b2532be9f1c449a3726fe5440ab4213a \
    --local-dir "$NV_SEGMENT_CTMR_ROOT/models/"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  mv "$NV_SEGMENT_CTMR_ROOT/models/vista3d_pretrained_model/model.pt" \
    "$NV_SEGMENT_CTMR_ROOT/models/model.pt"

NV_SEGMENT_CTMR_ROOT が未設定の場合、または必要なバンドルレイアウトになっていない場合、ラッパーは .workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR も検索します。

エージェントが生成するユーザー実行コマンドには、Usage に記載されているコマンドを使用してください。初回セットアップ用の Preconditions ブロックを回答にコピーしないでください。$NV_SEGMENT_CTMR_ROOT の下にファイルを作成または書き込んだり、hf download を実行したり、ベンチマークまたはユーザー実行中に共有 upstream チェックアウト内のファイルを移動したりしないでください。Python 3.12 環境では、pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt" を前置しないでください。upstream の要件では NumPy 1.24.4 が固定されていますが、このバージョンはその環境で正常にビルドできません。新しい Python 環境では、ラッパーを実行する前に、上記の最小限の互換性のあるランタイム（monai>=1.5,<1.6、numpy<2、nibabel、scipy、typer、PyYAML、fire、huggingface_hub、pytorch-ignite、einops）をインストールしてください。モデルがキャッシュされていても、Python パッケージがキャッシュされているとは限りません。

ランタイムには CUDA 対応の NVIDIA GPU が必要です。upstream バンドルは CPU のみのホストでもインポートできる場合がありますが、公開されているワークフローは 3D CT/MRI 基盤モデルの推論経路であるため、このスキルは CUDA 必須として宣言されています。

使用方法

Medical AI Skills のリポジトリルートから実行します。

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz \
  --modality CT_BODY \
  --output-dir runs/nv_segment_ctmr_demo

PATH_TO_IMAGE.nii.gz をユーザーの実際の入力パスに置き換えてください。ユーザー実行で、例として示されているフィクスチャパスをコピーしないでください。ユーザーが runs/ 内の入力パスを明示的に指定した場合、そのパスを scripts/run_ctmr.py の最初の位置引数にする必要があります。

自動セグメンテーションでサポートされるモダリティは CT_BODY、MRI_BODY、MRI_BRAIN です。MRI_BRAIN の場合、upstream README ではバンドル推論の前に脳専用の前処理が必要とされています。前処理済みの画像をこのラッパーに渡してください。

--label-prompts "3,14" を渡すと、モダリティ単位の「すべてをセグメント化」セットのみを使用する代わりに、特定の upstream クラス ID を指定できます。エビデンス出力には、入力ジオメトリ、出力マスクのパス、観測されたラベル ID、想定外のラベル、クラスごとのボクセル数、マスクヘッダーの間隔に基づくクラスごとの物理体積、実行時間、upstream コマンド、モデルインベントリ、ジオメトリのチェックが記録されます。

--ground-truth PATH を渡すと、input.ground_truth_path に参照ラベルマップのパスが記録されます。このスキルは Dice を計算しません。計算は対応する検証ツールの役割です。

CT 身体部位の出力については、verifiers/ct_segmentation_quality_v1 で解剖学的な妥当性と、記録された正解データに対するクラスごとの任意の Dice/IoU を確認できます。

臨床的な解釈、本番環境への導入、自律的な診断、または規制当局への申請には使用しないでください。