
名称	dicom-series-to-volume
描述	用于将一个CT DICOM序列文件夹转换为带有仿射信息的HU NIfTI体积。不适用于多帧DICOM或临床用途。
开源协议	Apache-2.0 allowed-tools: Bash metadata:
作者	NVIDIA医疗技术团队 tags: - 医疗技术 - DICOM - NIfTI

dicom_series_to_volume

目的

用于将一个CT DICOM序列文件夹转换为带有仿射信息的HU NIfTI体积。不适用于多帧DICOM或临床用途。
请完全按照文档使用包装器；不要用自行编写的实现替换上游入口点。
Manifest 输入/输出：输入是 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` 发生漂移。	安装 manifest 中声明的包，或使用文档记录的设置命令。
输出为空或不符合 schema	输入路径错误、模态不支持或上游失败。	使用已知夹具重新运行并检查包装器 JSON 和 stderr。
验证门失败	输出违反了声明的工程不变式。	保留失败的证据包，并使用门消息修复输入或包装器代码。

读取一个 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 结构集、自动重定向或临床使用。