dicom-series-to-volume

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dicom_series_to_volume

Purpose

用途

Used for converting one CT DICOM series folder to a HU NIfTI volume with affine evidence. Not for multi-frame DICOM or clinical use.
Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
Manifest I/O: inputs are
```
dicom_dir
```
; outputs are
```
nifti_volume
```
and
```
result_json
```
.

用于将单个CT DICOM序列文件夹转换为带有仿射信息的HU NIfTI体积。不适用于多帧DICOM或临床用途。
严格按照文档说明使用该封装器；请勿用手写实现替换上游入口点。
清单输入输出：输入为
```
dicom_dir
```
；输出为
```
nifti_volume
```
和
```
result_json
```
。

Instructions

使用说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/series_to_volume.py
```
through the documented command below; keep outputs under a caller-provided run directory.
If a host agent exposes
```
run_script
```
, use
```
run_script("scripts/series_to_volume.py", args=[...])
```
; otherwise run the Bash/Python command shown below.
Check the emitted JSON and the paired
```
dicom_volume_quality_v1
```
verifier before treating the run as evidence.

在修改参数、副作用或验证规则前，请先阅读
```
skill_manifest.yaml
```
。
通过下方文档中记录的命令运行
```
scripts/series_to_volume.py
```
；将输出保存在调用方指定的运行目录下。
如果宿主Agent暴露了
```
run_script
```
接口，请使用
```
run_script("scripts/series_to_volume.py", args=[...])
```
；否则运行下方所示的Bash/Python命令。
在将运行结果作为有效证据前，请检查生成的JSON文件以及配套的
```
dicom_volume_quality_v1
```
验证器。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/series_to_volume.py`	Primary entrypoint declared by skill_manifest.yaml.	`PATH_TO_DICOM_DIR [--output OUT.nii.gz]`

脚本	用途	参数
`scripts/series_to_volume.py`	`skill_manifest.yaml` 中声明的主要入口点。	`PATH_TO_DICOM_DIR [--output OUT.nii.gz]`

Prerequisites

前置条件

Runtime requirements: Python packages listed in
```
runtime.side_effects.pip_packages
```
.
Run commands from the repository root unless an existing section below says otherwise.

运行时要求：
```
runtime.side_effects.pip_packages
```
中列出的Python包。
除非下方现有章节另有说明，否则请从仓库根目录运行命令。

Limitations

局限性

Single-series only; multi-series input is rejected at preflight.
Multi-frame DICOM (NumberOfFrames > 1 per file) not supported.
Compressed transfer syntaxes (JPEG / JPEG2000 / RLE) not supported.
No voxel reorientation. The affine is derived from DICOM headers and represented in NIfTI/RAS coordinates; a downstream gate (e.g. expected_axcodes) is expected to assert orientation before this volume is fed to a segmentation model.
Not for clinical deployment, autonomous diagnosis, regulatory submission, production inference (use a vetted converter such as dcm2niix for that).

仅支持单序列；预检查阶段会拒绝多序列输入。
不支持多帧DICOM（每个文件的NumberOfFrames > 1）。
不支持压缩传输语法（JPEG / JPEG2000 / RLE）。
不支持体素重定向。仿射信息由DICOM头文件导出，并以NIfTI/RAS坐标表示；在将该体积输入分割模型前，预期下游会有验证环节（如expected_axcodes）来确认方向。
不适用于临床部署、自主诊断、合规申报或生产推理（此类场景请使用经过验证的转换器，如dcm2niix）。

Troubleshooting

故障排除

Error	Cause	Fix
Missing dependency or import error	Runtime package drift from `skill_manifest.yaml` .	Install the packages declared in the manifest or use the documented setup command.
Empty or schema-invalid output	Wrong input path, unsupported modality, or upstream failure.	Re-run with a known fixture and inspect the wrapper JSON plus stderr.
Validation gate failure	Output violated a declared engineering invariant.	Keep the failed evidence pack and use the gate message to repair inputs or wrapper code.

Reads one DICOM series, sorts slices by

ImagePositionPatient

, applies

RescaleSlope

and

RescaleIntercept

, builds an affine from orientation and spacing tags, and writes a

.nii.gz

plus JSON summary.

bash

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

For a trusted run with the paired verifier:

bash

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

Key output fields:

n_slices

series_instance_uid

output.path

output.shape

output.spacing

output.axcodes

output.affine

hu_range

, and

runtime.conversion_seconds

Scope limits: single-series CT only; no multi-frame DICOM, compressed transfer syntax handling, RT structure sets, auto-reorientation, or clinical use.

错误	原因	解决方法
依赖缺失或导入错误	运行时包与 `skill_manifest.yaml` 不一致。	安装清单中声明的包，或使用文档中记录的设置命令。
输出为空或不符合Schema规范	输入路径错误、模态不支持或上游执行失败。	使用已知的测试用例重新运行，并检查封装器的JSON输出以及标准错误流。
验证规则失败	输出违反了已声明的工程约束。	保留失败的证据包，并根据验证规则提示信息修复输入或封装器代码。

读取单个DICOM序列，按

ImagePositionPatient

对切片排序，应用

RescaleSlope

和

RescaleIntercept

，从方向和间距标签构建仿射矩阵，然后写入

.nii.gz

文件及JSON摘要。

bash

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

如需使用配套验证器进行可信运行：

bash

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结构集、自动重定向或临床用途。