Back to Details

dicom-series-preflight

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DICOM Series Preflight

DICOM系列预检

Purpose

用途

  • Used for header-only preflight of one DICOM series folder before conversion or inference. Not for de-identification or clinical clearance.
  • 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 
    preflight_json
    .
  • 用于在转换或推理前对单个DICOM系列文件夹进行仅针对文件头的预检。不用于去标识处理或临床审批。
  • 严格按照文档说明使用该封装程序；请勿用手写实现替换上游入口点。
  • 清单输入输出：输入为
    dicom_dir
    ；输出为
    preflight_json
    。

Instructions

使用说明

  • Read 
    skill_manifest.yaml
    before changing arguments, side effects, or validation gates.
  • Run 
    scripts/preflight_series.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/preflight_series.py", args=[...])
    ; otherwise run the Bash/Python command shown below.
  • Check the emitted JSON and paired verifier guidance before treating the run as evidence.
  • 在修改参数、副作用或验证规则前，请先阅读
    skill_manifest.yaml
    。
  • 通过下方文档记录的命令运行
    scripts/preflight_series.py
    ；将输出保存在调用方指定的运行目录下。
  • 如果宿主Agent暴露了
    run_script
    接口，请使用
    run_script("scripts/preflight_series.py", args=[...])
    ；否则运行下方所示的Bash/Python命令。
  • 在将运行结果作为依据前，请检查生成的JSON文件及配套的验证器指南。

Available Scripts

可用脚本

ScriptPurposeArguments
scripts/preflight_series.py
Primary entrypoint declared by skill_manifest.yaml.
PATH_TO_DICOM_DIR
脚本用途参数
scripts/preflight_series.py
skill_manifest.yaml
中声明的主入口点。
PATH_TO_DICOM_DIR

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

局限性

  • Header-only; does not decode pixel data or detect burnt-in PHI.
  • Canonical orientation gate assumes LPS-derived CT axcodes L,P,S.
  • Compressed transfer syntax and multi-frame instances are warned, not decoded.
  • Single-directory scan; does not reconcile multiple studies in one tree.
  • Not for clinical deployment, regulatory de-identification, autonomous diagnosis, production ingestion without a vetted converter.
  • 仅处理文件头；不解码像素数据或检测内嵌的受保护健康信息（PHI）。
  • 标准方向验证规则假设LPS坐标系的CT轴代码为L、P、S。
  • 对压缩传输语法和多帧实例仅发出警告，不进行解码。
  • 仅扫描单个目录；不处理同一目录树中的多个研究。
  • 不适用于临床部署、合规性去标识处理、自主诊断，或未经验证的转换器进行生产环境数据导入。

Troubleshooting

故障排查

ErrorCauseFix
Missing dependency or import errorRuntime package drift from 
skill_manifest.yaml
.		Install the packages declared in the manifest or use the documented setup command.
Empty or schema-invalid outputWrong input path, unsupported modality, or upstream failure.Re-run with a known fixture and inspect the wrapper JSON plus stderr.
Validation gate failureOutput violated a declared engineering invariant.Keep the failed evidence pack and use the gate message to repair inputs or wrapper code.
Scans a DICOM directory (one series per folder) without decoding pixels. Emits JSON with inventory, orientation axcodes, PHI flags, findings, and a 
preflight.verdict
of 
pass
, 
warn
, or 
fail
.
bash
python scripts/preflight_series.py PATH_TO_DICOM_DIR
Pair with 
verifiers/dicom_preflight_quality_v1
for a trusted preflight pack:
bash
make run-trusted SKILL=dicom_series_preflight \
  FIXTURE=skills/dicom-series-preflight/fixtures/clean_no_phi \
  OUT=runs/dicom_preflight_demo
Flagship workflow:
bash
make run-workflow \
  WORKFLOW=examples/workflows/dicom_preflight_gate.yaml \
  WORKFLOW_INPUT=skills/dicom-series-preflight/fixtures/clean_no_phi \
  WORKFLOW_OUT=runs/dicom_preflight_gate
Not for de-identification, private-tag review, or clinical clearance.
错误原因解决方法
依赖缺失或导入错误运行时包与
skill_manifest.yaml
不一致。		安装清单中声明的包，或使用文档记录的设置命令。
输出为空或不符合Schema规范输入路径错误、模态不支持或上游执行失败。使用已知的测试用例重新运行，并检查封装程序的JSON输出及标准错误信息。
验证规则失败输出违反了已声明的工程约束。保留失败的证据包，并根据验证规则提示修复输入或封装程序代码。
扫描DICOM目录（每个文件夹对应一个系列），不解码像素数据。 生成包含清单、方向轴代码、PHI标记、检测结果的JSON文件，以及
preflight.verdict
字段，取值为
pass
、
warn
或
fail
。
bash
python scripts/preflight_series.py PATH_TO_DICOM_DIR
搭配
verifiers/dicom_preflight_quality_v1
使用，可获得可信的预检包：
bash
make run-trusted SKILL=dicom_series_preflight \
  FIXTURE=skills/dicom-series-preflight/fixtures/clean_no_phi \
  OUT=runs/dicom_preflight_demo
典型工作流：
bash
make run-workflow \
  WORKFLOW=examples/workflows/dicom_preflight_gate.yaml \
  WORKFLOW_INPUT=skills/dicom-series-preflight/fixtures/clean_no_phi \
  WORKFLOW_OUT=runs/dicom_preflight_gate
不用于去标识处理、私有标签审查或临床审批。