dicom-series-to-volume

dicom_series_to_volume

目的

• CT DICOM シリーズフォルダーを、アフィン情報の証拠を含む HU NIfTI ボリュームに変換するために使用します。マルチフレーム DICOM や臨床用途には対応していません。
• ラッパーはドキュメントのとおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• マニフェストの入出力：入力は 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 パッケージ。
• 再配向時に極端な斜交軸のラベルを一貫して維持するには、NiBabel 5.4 以降が必要です。
• 以下の既存セクションに別途記載がない限り、リポジトリのルートからコマンドを実行してください。

制限事項

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

トラブルシューティング

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

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 構造セット、自動再配向、臨床用途には対応していません。