Python 运行外部命令的方法比较
==============================

问题背景
--------

在调用 dcm2niix 时，不同的 Python 执行方法可能产生不同的结果：

- **终端直接运行**：得到 3D 图像 (512, 512, 80)
- **Python subprocess.run**：得到 4D 图像 (512, 512, 40, 2)

本文档比较各种 Python 执行外部命令的方法。

方法对比表
----------

+---------------------+--------+-----------+---------+------------------------+
| 方法                | 简易度 | 终端相似度 | 输出控制 | 推荐用于dcm2niix     |
+=====================+========+===========+=========+========================+
| ``os.system()``     | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐      | ✅ **强烈推荐**        |
+---------------------+--------+-----------+---------+------------------------+
| ``subprocess.run()`` | ⭐⭐⭐⭐ | ⭐⭐⭐    | ⭐⭐⭐⭐ | ⚠️ 可能有问题         |
+---------------------+--------+-----------+---------+------------------------+
| ``subprocess.Popen()``| ⭐⭐  | ⭐⭐⭐    | ⭐⭐⭐⭐⭐| ✅ 可尝试             |
+---------------------+--------+-----------+---------+------------------------+
| ``subprocess.call()``| ⭐⭐⭐⭐ | ⭐⭐⭐    | ⭐⭐    | ⚠️ 已过时             |
+---------------------+--------+-----------+---------+------------------------+
| ``os.popen()``      | ⭐⭐⭐ | ⭐⭐      | ⭐⭐    | ❌ 已弃用             |
+---------------------+--------+-----------+---------+------------------------+

详细说明
--------

1. os.system() - 最推荐用于 dcm2niix ✅
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**特点**：

- 最接近在终端直接输入命令
- 行为与 shell 完全一致
- 输出直接显示在控制台
- 无法捕获输出内容

**示例**：

.. code-block:: python

   import os

   cmd = 'dcm2niix.exe -b n -m 2 -z y -o output input'
   exit_code = os.system(cmd)

   if exit_code != 0:
       print(f"命令失败，退出码: {exit_code}")

**优点**：

- ✅ 与终端行为完全一致
- ✅ 最简单直接
- ✅ 对 dcm2niix 问题最有效

**缺点**：

- ❌ 无法捕获输出内容
- ❌ 安全性较低（shell 注入风险）
- ❌ 返回码在不同平台可能不同

**适用场景**：

- **解决 dcm2niix 3D/4D 问题的首选方案**
- 不需要处理命令输出
- 命令来自可信源

2. subprocess.run() - 标准方法 ⚠️
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**特点**：

- Python 3.5+ 推荐的标准方法
- 可以捕获输出
- 更好的错误处理

**示例**：

.. code-block:: python

   import subprocess

   cmd = 'dcm2niix.exe -b n -m 2 -z y -o output input'

   # 方式A: 直接显示输出
   result = subprocess.run(
       cmd,
       shell=True,
       capture_output=False,
       text=True,
       check=True
   )

   # 方式B: 捕获输出
   result = subprocess.run(
       cmd,
       shell=True,
       capture_output=True,
       text=True,
       check=True
   )
   print(result.stdout)
   print(result.stderr)

**优点**：

- ✅ 标准推荐方法
- ✅ 可以捕获输出
- ✅ 更好的错误处理
- ✅ 支持超时控制

**缺点**：

- ❌ 可能与终端行为略有不同
- ❌ 对 dcm2niix 可能产生意外的 4D 输出

**适用场景**：

- 需要处理命令输出
- 需要错误处理
- 一般情况下的命令执行

3. subprocess.Popen() - 高级控制 ✅
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**特点**：

- 最灵活的方法
- 可以实时读取输出
- 可以进行进程间通信

**示例**：

.. code-block:: python

   import subprocess

   cmd = 'dcm2niix.exe -b n -m 2 -z y -o output input'

   # 实时输出
   process = subprocess.Popen(
       cmd,
       shell=True,
       stdout=subprocess.PIPE,
       stderr=subprocess.STDOUT,
       text=True,
       bufsize=1
   )

   # 逐行打印输出
   for line in process.stdout:
       print(line, end='')

   # 等待完成
   process.wait()
   exit_code = process.returncode

   if exit_code != 0:
       print(f"命令失败，退出码: {exit_code}")

**优点**：

- ✅ 最灵活的控制
- ✅ 可以实时处理输出
- ✅ 可以与进程交互
- ✅ 可能比 subprocess.run 更接近终端行为

**缺点**：

- ❌ 代码较复杂
- ❌ 需要手动处理进程通信

**适用场景**：

- 需要实时处理命令输出
- 需要长时间运行的进程
- 需要与进程交互
- subprocess.run 无法解决问题时的备选方案

4. subprocess.call() - 旧式方法
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**特点**：

- Python 2.x 的标准方法
- Python 3.5+ 已被 subprocess.run 替代

**示例**：

.. code-block:: python

   import subprocess

   cmd = 'dcm2niix.exe -b n -m 2 -z y -o output input'
   exit_code = subprocess.call(cmd, shell=True)

**推荐**：使用 ``subprocess.run()`` 代替

5. os.popen() - 已弃用
^^^^^^^^^^^^^^^^^^^^^^^

不推荐使用，已被 subprocess 模块替代。

在 habit 中的实现
----------------

当前代码位置：``habit/core/preprocessing/dcm2niix_converter.py`` (第 321 行)

快速切换执行方法
^^^^^^^^^^^^^^^^^^

在代码第 321 行修改 ``execution_method`` 变量：

.. code-block:: python

   execution_method = "os.system"  # 推荐：最接近终端行为
   # execution_method = "subprocess.run"  # 备选：标准方法
   # execution_method = "subprocess.Popen"  # 备选：实时输出

当前默认设置
^^^^^^^^^^^^^^

.. code-block:: python

   execution_method = "os.system"  # 默认使用os.system解决3D/4D问题

解决 dcm2niix 3D/4D 问题的推荐方案
----------------------------------

方案 1：使用 os.system（首选）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

   execution_method = "os.system"

**理由**：

- 与终端行为完全一致
- 已在代码中实现
- 无需修改，直接运行即可

方案 2：使用 subprocess.Popen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

   execution_method = "subprocess.Popen"

**理由**：

- 如果 os.system 也有问题，尝试这个
- 保留了输出捕获能力
- 比 subprocess.run 更接近终端

方案 3：直接在终端运行命令
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

查看程序输出的命令，复制到终端直接运行：

.. code-block:: bash

   # 复制Python输出的这段命令
   dcm2niix.exe -b n -l y -m 2 -p n -v y -z y -o "output_dir" "input_dir"

   # 直接在PowerShell或CMD中粘贴运行

测试步骤
--------

1. **使用 os.system 运行**（默认）：

   .. code-block:: bash

      python debug_preprocess.py

2. **检查输出维度**：

   .. code-block:: bash

      python verify_nifti_dimension.py

3. **如果还是 4D，修改代码第 321 行**：

   .. code-block:: python

      execution_method = "subprocess.Popen"

   然后重新运行步骤 1-2

4. **如果都不行，检查参数**：

   - 修改 ``dcm2nii.yaml`` 中的 ``merge_slices`` 和 ``single_file_mode``
   - 运行 ``test_dcm2nii_params.py`` 测试所有参数组合

常见问题
--------

Q: 为什么 os.system 最接近终端？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A: 因为 os.system 直接调用系统 shell 执行命令，没有任何 Python 的封装层，就像你在终端直接输入命令一样。subprocess 模块虽然也可以使用 shell=True，但增加了额外的处理层。

Q: os.system 安全吗？
^^^^^^^^^^^^^^^^^^^

A: 如果命令字符串来自用户输入，存在 shell 注入风险。但在我们的场景中：

- 命令是程序内部构建的
- 路径来自配置文件
- 不接受不可信的用户输入
- 因此是安全的

Q: 为什么不同方法会产生不同结果？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A: 可能的原因：

1. **环境变量差异**：subprocess 可能继承不同的环境变量
2. **工作目录**：不同方法的默认工作目录可能不同
3. **Shell 解析差异**：引号、空格等的处理方式可能略有不同
4. **缓冲区处理**：输出缓冲的处理可能影响某些程序的行为

Q: 我应该使用哪个方法？
^^^^^^^^^^^^^^^^^^^^^^^

A: 对于 dcm2niix 的 3D/4D 问题：

1. **首选**：``os.system``（已设为默认）
2. **备选 1**：``subprocess.Popen``
3. **备选 2**：调整 dcm2niix 参数（merge_slices, single_file_mode）
4. **最后手段**：直接在终端运行，手动复制结果

参考资料
--------

- `Python subprocess 官方文档 <https://docs.python.org/3/library/subprocess.html>`_
- `os.system 官方文档 <https://docs.python.org/3/library/os.html#os.system>`_
- `dcm2niix GitHub <https://github.com/rordenlab/dcm2niix>`_

更新日志
--------

- **2025-10-29**:
  - 添加多种执行方法支持
  - 默认使用 os.system 解决 3D/4D 问题
  - 提供方法切换机制