安装与上手

包名与安装方式

分发名、Python 导入名和命令行均为 brainfc。安装 PyPI 已发布版本并启动：

pip install brainfc
brainfc serve

可用版本以 PyPI 项目页 为准。如果目标版本尚未发布，或需要源码版，按下方本地方式安装。

从源码或本地安装包安装

需要 Python 3.11 或更高版本。完整验证环境是 Windows / Python 3.12；其他平台由新增 CI 配置覆盖，远程 CI 实际结果需发布后查看。

在解压后的源码根目录执行：

python -m venv .venv
# Windows
.venv\Scripts\python -m pip install .
.venv\Scripts\brainfc serve
# macOS / Linux：改用 .venv/bin/python 和 .venv/bin/brainfc

已激活自己的虚拟环境时，只需 python -m pip install . 和 brainfc serve。默认安装已包含全部 Python API 和本地网页依赖，不需要另外选择 extras。

本地 wheel 安装：

python -m pip install "brainfc-0.3.0-py3-none-any.whl"
brainfc --version
brainfc serve

wheel 内含网页和离线手册。普通使用不需要 Node.js；首次安装仍需获取 Python 依赖。完全断网安装需提前准备依赖 wheel 或已有依赖环境。

第一次运行

服务默认打开 http://127.0.0.1:8766。点击“试用演示”可生成合成 NIfTI、提取 12 个人工脑区、计算矩阵并导出图像。演示不下载患者数据。

自己的数据按 选择数据 → 确认处理方案 → 开始处理 操作。可一次选择主文件和配套 JSON/confounds/mask。TR、空间及配套文件能明确识别时自动填入；剩余高级参数可展开调整。不能确定空间或预处理状态的影像须先核对。

默认工作目录是 ~/brainfc-workspace。自定义端口/目录：

brainfc serve --port 8767 --workspace ./workspace --no-browser

同一工作目录只使用一个服务进程。关闭服务可能中断正在处理的任务；下次启动时遗留任务标为 interrupted，需要新建任务重新运行。

不用界面的最短演示

brainfc demo --output ./demo-001

demo-001 必须不存在。input/ 是合成输入，result/ 包含数组、CSV/TSV、PNG/SVG/PDF、质控、来源和离线 report.html。

Python 可执行例子在源码的 examples/quickstart.py 和 examples/roi_timeseries.py，两者均不需要网络。完整函数说明见 API 参考。

原始扫描入口

brainfc dicom ./dicom --output ./converted
# 加 --run 才执行；需预先安装 dcm2niix。
brainfc preprocess ./bids --output ./derivatives --license ./license.txt --participant 01
# 核对命令后加 --run；需 Docker Linux 容器。

转换完成后需要按采集信息组织 BIDS。fMRIPrep 完成并检查报告后，将 desc-preproc_bold 输入本库。具体输入责任见 格式说明，处理边界见 方法说明。

常见错误