nv-segment-ctmr

NV-Segment-CTMR

目的

• CT または MRI の NIfTI ボリュームで NV-Segment-CTMR を実行し、ラベルマップのエビデンスを記録するために使用します。臨床的解釈には使用しないでください。
• ラッパーは文書どおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• マニフェスト I/O：入力は 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、runtime.side_effects.pip_packages に記載された Python パッケージ。
• 副作用：呼び出し側の --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:-.workbench_data/upstreams/NV-Segment-CTMR/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/...、または共有上流チェックアウト内で ファイルを作成、ダウンロード、移動するその他のコマンドが含まれている場合、そのブロックは無効です。

前提条件

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

上流バンドルを一度だけクローンしてインストールします。この Medical AI Skills のチェックアウトでは、 存在する場合はリポジトリローカルのキャッシュパスを優先してください：

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Segment-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git \
    .workbench_data/upstreams/NV-Segment-CTMR
export NV_SEGMENT_CTMR_ROOT=.workbench_data/upstreams/NV-Segment-CTMR/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 -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 --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 を実行せず、ベンチマーク中またはユーザー実行時に共有上流チェックアウト内のファイルを移動しないでください。 Python 3.12 環境では、pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt" を前置しないでください。 上流の requirements は 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 が必要です。上流バンドルは CPU のみのホストでもインポートできる場合がありますが、公開されているワークフローは 3D CT/MRI 基盤モデルの推論パスであるため、このスキルは CUDA 必須として宣言されています。

使用方法

Medical AI Skills リポジトリのルートから：

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/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 では、バンドル推論の前に脳専用の前処理が必要だと上流 README に記載されています。 このラッパーには、前処理済みの画像を渡してください。

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

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

CT-body の出力については、解剖学的妥当性と、記録された正解データとのクラスごとの Dice／IoU（任意）を verifiers/ct_segmentation_quality_v1 で確認できます。

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