girder/slicer_cli_web

Slicer CLI Web 技术文档

1. 概述

Slicer CLI Web 是一个Girder插件，通过Docker和girder_worker在Web上暴露Slicer执行模型的CLI模块，允许从Girder用户界面运行容器化任务。

2. 核心功能与特性

• Web化CLI访问：将Docker化的Slicer CLI工具通过Web界面暴露
• Docker镜像管理：支持导入和管理Docker化的CLI工具
• 任务执行与监控：通过Girder Worker执行CLI任务并提供进度监控
• REST API接口：提供REST端点以编程方式调用CLI
• 批处理支持：对文件夹中的多个项目执行批量处理
• 模板化输入：支持Jinja2风格的模板字符串自动填充参数

3. 使用场景与适用范围

• 医学影像分析与处理工作流
• 需要通过Web界面访问命令行工具的场景
• 批量处理医学影像数据
• 构建基于Slicer执行模型的Web应用
• 科研团队共享和使用CLI工具

4. 安装与配置

4.1 系统要求

• Python 3.6、3.7、3.8或3.9
• MongoDB（已安装并运行）
• RabbitMQ或其他消息代理（用于Girder Worker）
• Docker（当前用户需属于docker用户组）

4.2 安装步骤

4.2.1 Girder插件安装

bash
pip install girder-slicer-cli-web[girder]
girder build
girder serve

4.2.2 Girder Worker安装

bash
pip install girder-slicer-cli-web[worker]
GW_DIRECT_PATHS=true girder_worker -l info -Ofair --prefetch-multiplier=1

4.3 初始配置

首次启动Girder时，需要：

1. 创建至少一个用户和一个资产存储（参见Girder文档）
2. 安装Docker化任务（如HistomicsTK算法）：
   • 进入管理控制台 → 插件 → Slicer CLI Web设置
   • 设置默认任务上传文件夹
   • 导入Docker镜像（例如：dsarchive/histomicstk:latest）

5. 使用方法

5.1 Girder插件使用

5.1.1 导入Docker镜像

1. 以管理员用户身份进入Girder管理控制台 → 插件 → Slicer CLI Web
2. 选择Docker镜像和现有文件夹，然后点击"导入镜像"
3. 如果Girder服务器上没有该镜像，Slicer CLI Web将自动拉取

导入后会创建以下结构：

• 以镜像标签命名的文件夹
• 该文件夹内包含以镜像版本命名的子文件夹
• 子文件夹中为每个CLI创建一个项目项

5.1.2 运行CLI

1. 访问已导入CLI的项目页面
2. 在"配置任务"部分设置所有输入参数并指定输出文件存储位置
3. 点击"运行任务"，Girder Worker将执行该CLI
4. 在"作业"面板中查看进度和错误消息

5.2 Docker CLI规范

5.2.1 基本要求

任何符合以下要求的Docker镜像都可用于Slicer CLI Web：

1. 列出CLI：执行以下命令时返回JSON字典

   bash
   docker run <docker image tag> --list_cli
   

   JSON字典的键为CLI名称，参见https://github.com/girder/slicer_cli_web/blob/master/small-docker/cli_list.json%E7%A4%BA%E4%BE%8B%E3%80%82

2. CLI XML规范：执行以下命令时返回XML规范

   bash
   docker run <docker image tag> <cli name> --xml
   

   XML必须符合Slicer执行模式，参见https://github.com/girder/slicer_cli_web/blob/master/small-docker/Example1/Example1.xml%E7%A4%BA%E4%BE%8B%E3%80%82

5.2.2 XML扩展规范

除标准Slicer执行模式外，支持以下扩展：

• 属性扩展：

  • image、file、transform、geometry、table类型可具有reference属性
  • region类型可具有coordinateSystem属性
  • image、file、item、directory类型可具有defaultNameMatch和defaultPathMatch属性（正则表达式）

• 自动填充参数：

  • girderApiUrl：自动填充Girder API URL
  • girderToken：自动填充Girder访问令牌

5.3 CLI端点

每个暴露的CLI通过以下REST路径添加为端点：

• slicer_cli_web/<docker image tag and version>/<cli command>/run
• slicer_cli_web/<internal item id>/run

其中<docker image tag and version>是标签和版本的组合，斜杠、冒号和@符号替换为下划线。

所有命令行参数可作为端点查询参数传递：

• 输入项、文件夹和文件通过Girder ID指定
• 输入图像通过Girder文件ID指定
• 输出文件通过名称指定，并带有相同名称加_folder后缀的参数（含Girder文件夹ID）

5.4 批处理

对包含多个项目的文件夹执行批量处理：

• 非批处理：通过<param>传递图像、项目或文件的ID
• 批处理：通过<param>_folder传递文件夹ID，并通过<param>传递正则表达式

批处理要求：

• 如果指定多个输入批处理规范，文件夹ID和正则表达式确定的项目列表必须一一对应
• 所有列表按小写项目名称排序枚举
• 父作业仅在最近的子作业不再等待启动时才启动另一个子作业
• 可以取消父作业以停止调度更多子作业

5.5 模板化输入

CLI参数支持Jinja2风格的模板字符串，未指定或为空时自动填充：

5.5.1 通用模板值

• {{title}}：CLI任务显示标题
• {{task}}：内部任务名称
• {{image}}：任务使用的Docker镜像标签
• {{now}}：作业开始的本地时间（格式：yyyymmdd-HHMMSS）
• {{parameter_<name>}}：引用其他参数值
• {{parameter_<name>_base}}：引用其他参数值（去除最右侧文件扩展名）

5.5.2 参数特定模板值

• {{name}}：参数名称
• {{label}}：参数标签（UI中显示）
• {{description}}：参数描述
• {{index}}：参数索引
• {{default}}：参数默认值
• {{extension}}：参数的第一个文件扩展名
• {{reference}}：引用参数的值
• {{reference_base}}：引用参数的值（去除最右侧文件扩展名）

6. 示例

6.1 构建示例CLI Docker镜像

bash
docker build --force-rm -t girder/slicer_cli_web:small .

6.2 运行Girder服务器

bash
# 安装Girder插件
pip install girder-slicer-cli-web[girder]

# 构建Girder
girder build

# 启动Girder服务器
girder serve

6.3 启动Girder Worker

bash
# 安装Worker插件
pip install girder-slicer-cli-web[worker]

# 启动Worker
GW_DIRECT_PATHS=true girder_worker -l info -Ofair --prefetch-multiplier=1

6.4 导入示例Docker镜像

bash
# 从Docker Hub拉取示例镜像
docker pull girder/slicer_cli_web:small

然后在Girder管理控制台中导入该镜像。

7. 配置参数与环境变量

7.1 Girder Worker环境变量

• GW_DIRECT_PATHS：设置为true以启用直接路径访问
• GIRDER_WORKER_LOG_LEVEL：日志级别（debug, info, warning, error, critical）
• GIRDER_WORKER_BROKER：消息代理URL（默认：amqp://guest@localhost//）

7.2 CLI XML扩展属性

• reference：用于image、file、transform、geometry、table类型
• coordinateSystem：用于region类型
• defaultNameMatch：文件名匹配正则表达式
• defaultPathMatch：文件路径匹配正则表达式

8. 参考链接

• Girder文档
• Girder Worker文档
• https://github.com/DigitalSlideArchive/HistomicsTK
• Slicer执行模型