sem_ruler 是一个面向扫描电镜（SEM）图像的标注小工具，支持在图像上自动绘制比例尺与长度文字，并针对浅色背景进行可读性优化（黑色描边）。它既可以通过网页界面拖拽使用，也支持容器化部署，适合实验室日常快速标注与结果分享。

• 前端页面（如果不想自行部署 可以直接访问使用）： sem-tool

为什么需要 sem_ruler

• 实验记录与论文投稿通常需要直观的比例尺与测量标注。
• 原始 SEM 图像的元数据与标注文件（TXT）格式不统一，手工添加既耗时又易出错。
• 浅色背景下的标注容易糊，需要稳定的描边策略保证可读性。

核心能力

• 自动加标尺与长度文字：支持有 TXT 和无 TXT 两种输入路径。
• 可读性优化：针对浅色图像自动添加黑色描边，随图像尺寸/字体动态缩放。
• 兼容常见格式：TIF/TIFF。
• 一键网页使用：拖拽上传、预览、下载处理结果。
• 容器化部署：提供 Docker 镜像，环境一致、开箱即用。

工作原理概述

• 有 TXT 场景：从 TXT 中解析放大倍率、像素尺寸或标尺信息，计算比例尺长度与文本内容；在图像上绘制矩形标尺和长度文字。
• 无 TXT 场景：从 TIF/TIFF 元数据中读取像素尺寸（依赖 tifffile），自动计算比例尺；同样绘制标尺与文字。
• 描边策略：process_sem_image.py 中按图像高度动态计算描边宽度（例如行内实现 stroke_w = max(2, int(round(h * 0.003)))），并为旧 Pillow 版本提供手动描边回退，确保不同环境下的稳定显示。

快速开始

本地运行（Python）

1) 安装依赖

python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

2) 启动应用

python run.py

3) 打开浏览器访问

http://127.0.0.1:5050

Docker 运行

如果不希望在本机配置 Python 环境，推荐使用容器：

docker pull kevinzhangyy/sem-ruler:1.0.0
docker run --rm -p 5050:5050 -v "${PWD}/data/uploads:/app/data/uploads" kevinzhangyy/sem-ruler:1.0.0

• 访问：http://127.0.0.1:5050
• 可选：将本地 data/uploads 映射到容器 /app/data/uploads，便于管理上传文件与输出。

Docker Compose（可选）

仓库中包含 docker-compose.yml，可按需调整挂载目录与端口，然后：

docker compose up -d

网页使用流程

1) 打开页面 http://127.0.0.1:5050
2) 拖拽或选择上传 TIF/TIFF/PNG 文件（可同时上传相应 TXT）
3) 点击处理，预览标注结果
4) 下载处理后的图片用于记录与报告

无 TXT 与有 TXT 的两条路径

• 有 TXT：解析文本中的参数，精确绘制比例尺与长度文字。
• 无 TXT：自动读取 TIF 元数据（需 tifffile），智能估算比例尺；并启用动态描边提升可读性。

两条路径都统一通过核心处理模块：。

可读性优化：动态描边与兼容回退

• 动态描边：根据图像尺寸动态计算 stroke_width，在浅色背景上确保线条与文字的清晰度。

常见问题（FAQ）

• Q：启动容器后提示 “tifffile not available”？

  • A：请使用最新镜像或在依赖中加入 tifffile。无 TXT 路径依赖该库读取 TIF 元数据。当前镜像 kevinzhangyy/sem-ruler:1.0.0 已包含该依赖，直接拉取即可。

• Q：浅色背景下标尺和文字看不清？

  • A：已启用黑色描边并随图像尺寸自动缩放。如仍不理想，可在 UI 中适当增大字体或标尺宽度。

• Q：支持哪些文件格式？

  • A：常用的 TIF/TIFF 均可，其他格式可先转换后使用。

路线图（Roadmap）

• 支持更多厂商/型号的 TIF 元数据解析
• 更灵活的模板与样式（位置、配色、字号一键切换）
• 批量处理与命令行接口（CLI）
• 多架构 Docker 镜像与 latest 标签维护

结语

如果你需要快速、稳定地为 SEM 图像添加比例尺与长度文字，sem_ruler 能在最少操作下给出清晰可读的标注效果。无论是本地还是 Docker 部署，都可以在数分钟内完成搭建并开始使用。欢迎在你的工作流程中尝试，并提出改进建议！