快速开始

安装 OmniPrep、获取 FreeSurfer 许可证，并在几分钟内完成你的第一个 BIDS 数据集预处理。

环境要求

OmniPrep 以自包含容器镜像发布，大部分依赖已内置。你需要准备：

要求	用途
Docker（或 Singularity / Apptainer）	运行工作流的容器运行时。
FreeSurfer 许可证文件	结构重建必需。免费——在此注册。
BIDS 格式数据集	按 BIDS 标准组织的数据。
GPU（可选）	加速可用步骤。可通过 `--device cpu` 回退到 CPU。

存储提示 多模态预处理会产生大量中间文件。磁盘空间紧张时请使用 --remove_temp_files。

安装

拉取最新的 OmniPrep 镜像，无需编译。

Docker

docker pull uxhao/omniprep:latest

验证镜像并打印内置帮助：

docker run --rm uxhao/omniprep:latest --help

Singularity / Apptainer

从 Docker 镜像构建 Singularity 镜像，或使用预构建的 .simg：

singularity pull omniprep.simg docker://uxhao/omniprep:latest

FreeSurfer 许可证

OmniPrep 结构重建需要一个有效的 FreeSurfer 许可证文件（license.txt），免费获取：

注册——在 surfer.nmr.mgh.harvard.edu/registration.html 填写表单。
下载 license.txt——你会通过邮件收到，保存到已知路径。
挂载——通过 --fs_license_file 传入路径（见下文）。

请勿分发许可证 每位用户需自行获取许可证，OmniPrep 从不内置许可证。

快速开始

最小运行需要三个挂载：BIDS 数据、输出目录和 FreeSurfer 许可证。

Docker

docker run -it --rm [--gpus all] \
  -v /path/to/bids:/data \
  -v /path/to/output:/out \
  -v /path/to/fs_license.txt:/license.txt \
  uxhao/omniprep:latest /data /out participant \
  --fs_license_file /license.txt \
  --tasks "anat bold dwi"

Singularity / Apptainer

singularity run [-nv] \
  --bind /path/to/bids:/data \
  --bind /path/to/output:/out \
  --bind /path/to/fs_license.txt:/license.txt \
  omniprep.simg \
  --fs_license_file /license.txt \
  --tasks "anat bold dwi"

不带参数运行会启动交互式 Streamlit Web 界面；带单个参数（--help）会打印完整参数参考。

运行示例

对所有被试执行多模态预处理

omniprep-docker /data /out participant \
  --fs_license_file /opt/freesurfer/license.txt \
  --tasks "anat bold dwi" \
  [options]

仅做 BOLD，复用已有结构衍生数据

omniprep-docker /data /out participant \
  --fs_license_file /opt/freesurfer/license.txt \
  --tasks "bold" \
  --subjects_dir /out/Recon \
  --participant_label "sub-001 sub-002" \
  [options]

当 --tasks 省略 anat 时，BOLD 和 DWI 工作流仍需要结构衍生数据（T1w、掩膜、表面、分割、分区）。通过 --subjects_dir 提供；若未指定，默认使用 output_dir/derivatives/omniprep/Recon。

输出结构

所有衍生数据都写入 output_dir/derivatives/omniprep：

output_dir/
└── derivatives/
    └── omniprep/
        ├── Recon/        # FreeSurfer 结构衍生数据
        ├── BOLD/         # 去噪 BOLD + 体素/ROI 指标
        ├── DWI/          # DTI/CSD 指标、纤维追踪、连接组
        ├── QC/           # 运行报告、trace、时间线
        └── WorkDir/      # Nextflow 工作与运行时状态

完整参数参考请见文档页面。