Histopia 3D组织学静态站点发布指南:GitHub Pages showcase 与 QC 门户手把手教程
Histopia 3D组织学静态站点发布指南:GitHub Pages showcase 与 QC 门户手把手教程
Histopia(Histology Spatial Topology for Omics Profiling and Inter-section Alignment)是一套用于组织学序列切片配准、细胞分割、染色定量、蛋白预测与空间组织重建的工具箱。本教程带你用它的 showcase 与 qc-showcase 命令,把 3D 组织学可视化结果一键导出为纯静态站点,并发布到 GitHub Pages 上——无需服务器、无 CDN 依赖,打开即用。
为什么选择静态导出?
组织学 3D 数据量通常很大,传统方案需要一个常驻后端服务来按需吐图。Histopia 的思路不同:把所有纹理、几何与运行时打包成一个自包含的静态目录,直接扔到 GitHub Pages 就能跑。核心优势:
- 零运行时依赖:Three.js 与 OpenSeadragon 均以固定版本随产物一起分发,构建时会校验运行时校验和,页面不发起任何第三方请求;
- 可审计:产物中的
showcase.json记录了每个文件的 SHA-256 摘要和语义/染色结果的指纹,方便追溯; - 免费托管:GitHub Pages 免费、稳定,一条链接就能分享给同事审稿。
💡 GitHub 的 README 无法内嵌可执行 JS,所以交互式 WebGL 应用由 GitHub Pages 托管,而不是塞进 README 里。
第 1 步:安装 Histopia 可视化依赖
静态 3D 站点导出依赖配准与 WSI 功能,推荐这样安装:
pip install "histopia[registration,wsi]"
如果你还想在站点里嵌入细胞级蛋白图谱,可再加上 cells、protein 等可选依赖组,详细说明见 docs/dependency_management.md。
第 2 步:用 showcase 命令导出静态站点
前提是你已经生成了 Histopia viewer 目录(含 manifest.json、纹理资产等)。然后执行:
histopia-visualize showcase \
/path/to/generated/viewer/histopia \
/path/to/new/showcase \
--mouse sample-a \
--mouse sample-b
参数要点(源码见 src/histopia/visualization/_cli.py):
| 参数 | 作用 |
|---|---|
--mouse |
要导出的样本 ID,可重复书写以导出整个队列,顺序即浏览器中的浏览顺序 |
--review-config |
启用原生分辨率 WSI 贴图时必需的本地审阅注册表 |
--wsi-section MOUSE=SECTION |
嵌入某个审批过的三位编号原生分辨率切片 |
--max-bytes |
WSI 贴图的硬字节预算,默认 900 MiB,超预算直接失败 |
--protein-atlas |
附带一份已构建好的细胞蛋白图谱静态产物 |
--protein-atlas-max-bytes |
蛋白图谱的独立大小上限,默认 650 MiB |
导出过程做了什么?
核心逻辑在 src/histopia/visualization/_showcase.py:
- 校验样本 ID 不重复、输出目录为空、路径非本机绝对路径;
- 拒绝未获指纹审批(fingerprint-approved)的语义或染色结果——保证发布内容与审查记录一致;
- 只复制所选样本的纹理,写入选定队列的
manifest.json; - 生成
.nojekyll标记(这是 GitHub Pages 静态托管的关键文件); - 输出
showcase.json完整性清单。
嵌入原生分辨率切片时,WSI 导出器会核对配准密封指纹,自动剔除全白瓦片,逐一清点保留瓦片,并在超出字节预算前报错,而不是悄悄截断。
第 3 步:发布到 GitHub Pages
仓库不直接跟踪生成的纹理,官方流程是把审批过的 showcase 打成版本化 Release 资产:
- 导出并浏览器实测队列中每个样本;
- 对导出目录做确定性压缩归档;
- 以
pages-demo-<cohort>-v<version>标签上传该归档; - 在
.github/workflows/pages.yml中更新归档名、URL 与 SHA-256; - 跑完测试套件后从默认分支触发部署。
Pages 工作流会下载指定 Release URL、校验归档 SHA-256、确认不含符号链接且包含两个本地运行时(Three.js 与 OpenSeadragon),然后部署。完整的发布步骤记录在 docs/github_pages_showcase.md。
第 4 步:构建 Registration QC 门户
除了主展示站,同一发布流程还提供一个独立的 /qc/ 门户,用于工作流诊断:
histopia-visualize qc-showcase \
/path/to/generated/viewer/histopia \
/path/to/new/showcase/qc \
--mouse sample-a
门户只包含所选审阅产物与配准组织学纹理,提供三个审阅阶段:
- Tissue masks(组织掩膜,必选阶段)
- Orientation & order(方向与切片排序)
- 3D registration(交互式 3D 配准视图)
语义纹理、原始切片、源码路径等一律排除(实现见 src/histopia/visualization/_qc_showcase.py)。如果某队列缺少方向/排序审阅记录,对应控件会显式禁用而不是用不完整数据重建——"阶段可见"本身不代表科学审批。
第 5 步:分享与互动
两个站点都支持可分享的 URL 查询参数:
- 主站点:
?mouse=sample-a直达某样本,切换样本时只更新 URL、不重载页面; - QC 门户:
?mouse=sample-a&stage=order同时定位样本与审阅阶段。
主站点内支持逐片导航、全选/取消图层、组织学/语义/混合渲染、K=5 至 K=15 邻域探索,以及相邻切片拓扑链接。渲染是按需驱动的:加载与相机移动时才重绘,场景静止即停止请求动画帧,显著降低后台 CPU/GPU 占用。
常见失败原因与排查清单
| 现象 | 原因 |
|---|---|
showcase output directory is not empty |
输出目录非空,导出器从不覆盖,换个空目录 |
semantic showcase result is not fingerprint-approved |
语义结果未经指纹审批,先完成审批再导出 |
WSI showcase requires a review configuration |
使用 --wsi-section 时必须同时给 --review-config |
| 超预算失败 | 调低 --max-bytes 或减少 --wsi-section 数量 |
| 部署后页面空白 | 确认归档包含 .nojekyll 与两个本地运行时 |
进阶:嵌入细胞蛋白图谱
已构建的细胞蛋白图谱可以整体嵌入 showcase,而不引入任何运行时服务——因为 Three.js、worker 代码、几何与蛋白值全部是相对路径静态资源。图谱队列集合必须与 showcase 样本集合完全一致,目录中不得含符号链接,并需同时满足图谱独立上限与总上限。科学契约详见 docs/cellular_protein_atlas.md。
小结
histopia-visualize showcase:导出自包含的 3D 组织学静态展示站,.nojekyll+ 本地运行时 + SHA-256 清单;histopia-visualize qc-showcase:导出三阶段审阅的/qc/诊断门户;- 发布走"版本化 Release 资产 + Pages 工作流",SHA-256 校验保证部署内容可复现;
- 指纹审批是发布前的硬门槛:未审批的结果无法进入静态站点。
更多文档入口见 docs/README.md,配准工作流细节见 docs/registration.md。