dicom-series-to-volume

dicom_series_to_volume

目的

• 1 つの CT DICOM シリーズフォルダーを、アフィン情報の根拠を含む HU NIfTI ボリュームに変換するために使用します。マルチフレーム DICOM や臨床用途には使用しないでください。
• ラッパーはドキュメントの記載どおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• マニフェスト I/O：入力は dicom_dir、出力は nifti_volume と result_json です。

手順

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

利用可能なスクリプト

スクリプト	目的	引数
scripts/series_to_volume.py	skill_manifest.yaml で宣言された主要なエントリーポイントです。	PATH_TO_DICOM_DIR [--output OUT.nii.gz]

前提条件

• 実行時の要件：runtime.side_effects.pip_packages に記載された Python パッケージ。
• 以下のセクションで別途指定されていない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• 単一シリーズのみ対応します。複数シリーズの入力は事前チェックで拒否されます。
• マルチフレーム DICOM（ファイルごとの NumberOfFrames > 1）には対応していません。
• 圧縮転送構文（JPEG / JPEG2000 / RLE）には対応していません。
• ボクセルの再配向は行いません。アフィンは DICOM ヘッダーから導出され、NIfTI/RAS 座標で表現されます。このボリュームをセグメンテーションモデルに渡す前に、下流のゲート（例：expected_axcodes）で向きを検証することを想定しています。
• 臨床導入、自律診断、規制当局への申請、本番推論には使用しないでください（その用途には、dcm2niix など、適切に検証されたコンバーターを使用してください）。

トラブルシューティング

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

1 つの DICOM シリーズを読み込み、ImagePositionPatient でスライスを並べ替え、RescaleSlope と RescaleIntercept を適用し、向きと間隔のタグからアフィンを構築して、.nii.gz と JSON の概要を書き出します。

python scripts/series_to_volume.py PATH_TO_DICOM_DIR --output PATH_TO_OUT.nii.gz

対になる検証ツールを使って信頼できる実行を行う場合：

python -m eval_engine.run_trusted skills/dicom-series-to-volume \
  --fixture PATH_TO_DICOM_DIR \
  --out runs/dicom_series_to_volume_trusted

主な出力フィールド：n_slices、series_instance_uid、output.path、output.shape、output.spacing、output.axcodes、output.affine、hu_range、runtime.conversion_seconds。

適用範囲の制限：単一シリーズの CT のみ対応します。マルチフレーム DICOM、圧縮転送構文の処理、RT structure sets、自動再配向、臨床用途には対応していません。