Genymobile/screen-ruler
GitHub: Genymobile/screen-ruler
一款基于边缘检测的智能屏幕标尺，鼠标悬停即可实时测量任意 UI 元素的宽高像素值。
Stars: 2 | Forks: 1
# screen-ruler
一款适用于 Linux 桌面的智能、基于边缘检测的屏幕标尺。
将鼠标光标移动到任何 UI 元素上，即可即时读取最近边缘之间的**宽度**和**高度**——无论是按钮、面板、窗口还是图标——无需点击或拖拽。
## 工作原理
启动时，screen-ruler 会进行一次性的屏幕截图，并使用 Canny 边缘检测构建二值边缘图（通过 OpenCV 高斯预模糊来抑制字体抗锯齿和壁纸噪点）。随后会在所有显示器上显示一个透明覆盖层。在每一帧中，从鼠标光标向四个方向（北 / 南 / 东 / 西）发射射线，直到它们碰到边缘像素或屏幕边界。东西方向的总距离将作为 **W** 报告，南北方向的总距离作为 **H** 报告，并实时显示在光标旁边的一个小标签中。
## 依赖项
| 包名 | 最低版本 |
|---|---|
| [PyQt6](https://pypi.org/project/PyQt6/) | 6.2 |
| [NumPy](https://pypi.org/project/numpy/) | 1.21 |
| [opencv-python-headless](https://pypi.org/project/opencv-python-headless/) | 4.5 |
一次性安装所有依赖项：
```
pip install -r requirements.txt
```
## 使用方法
```
python screen_ruler.py [--threshold-low N] [--threshold-high N] [--debug-edge-overlay]
```
| 选项 | 默认值 | 描述 |
|---|---|---|
| `--threshold-low N` | 29 | Canny 边缘检测器的低滞后阈值 |
| `--threshold-high N` | 101 | Canny 边缘检测器的高滞后阈值 |
| `--debug-edge-overlay` | off | 保持捕获的 Canny 边缘图可见（基础透明度）以便调试；滑动滑块也会触发短暂的边缘预览 |
**控制方式**
| 输入 | 动作 |
|---|---|
| `1` / `2` / `3` | 切换测量模式 |
| `Ctrl+C` | 将当前测量结果复制到剪贴板，然后退出 |
| `?` 或 `H` | 切换快捷键帮助覆盖层的显示 |
| `Escape` 或 `Q` | 退出 |
| 左键点击 | 将当前测量结果作为 `W × H px` 复制到剪贴板，然后退出 |
| 顶部 `Sensitivity` 滑块 | 实时重新计算边缘检测（防抖）并短暂显示边缘图预览（先保持显示然后淡出） |
启动时，会短暂显示一个轻量级的快捷键覆盖层并自动淡出；随时按 `?` 或 `H` 键可将其重新调出。
## 构建独立可执行文件
如果你不想安装 Python 环境，可以使用 [PyInstaller](https://pyinstaller.org) 构建一个独立的单文件二进制程序：
```
pip install -r requirements.txt -r requirements-build.txt
pyinstaller screen_ruler.spec
```
二进制文件将输出到 `dist/screen-ruler`。你可以将其复制到任何位置并直接运行——目标机器上无需安装 Python 或任何库。
## 全局键盘快捷键
Screen Ruler 的设计理念是即开即用——捕获、测量、退出。全局键盘快捷键可以让你无需常驻后台 daemon 即可瞬间召唤它。
### Linux
构建二进制文件后，运行安装脚本：
```
./install-linux.sh # installs to the current directory
./install-linux.sh -d ~/bin # or specify a directory
```
该脚本会复制二进制文件，安装一个 `.desktop` 条目，并自动为检测到的桌面环境（GNOME、KDE Plasma、Hyprland、Sway）注册 **Super+Shift+R** 快捷键。
### macOS
构建二进制文件后，运行安装脚本：
```
./install-macos.sh # installs to the current directory
./install-macos.sh -d ~/bin # or specify a directory
```
该脚本会复制二进制文件并创建一个 Automator 快速操作（“Launch Screen Ruler”）。然后前往 **系统设置 → 键盘 → 键盘快捷键 → 服务** 中绑定快捷键（例如 **⌘⇧R**）。
### Windows
构建可执行文件后，在 PowerShell 中运行安装脚本：
```
.\install-windows.ps1 # installs to the current directory
.\install-windows.ps1 -InstallDir "$env:LOCALAPPDATA\screen-ruler" # or specify a directory
```
该脚本会复制二进制文件，将其添加到用户的 `PATH` 中，并创建一个带有 **Ctrl+Shift+R** 热键的开始菜单快捷方式。
如需在任何平台上进行手动设置，请参阅 [docs/manual-shortcut-setup.md](docs/manual-shortcut-setup.md)。
## 故障排除
### X11 下覆盖层相对于顶部/侧边栏的偏移
在某些 X11 窗口管理器中，无框工具窗口会被限制在桌面工作区内（不包括面板/dock）。screen-ruler 在 X11 上使用了 `Qt.X11BypassWindowManagerHint`，因此覆盖层能够与用于捕获和测量的完整虚拟桌面坐标相匹配。
由于绕过窗口管理器的窗口在焦点行为上可能较难预测，该应用还额外安装了应用级别的 `Escape`/`Q` 按键作为备用退出方式。
### `qt.qpa.theme.gnome: dbus reply error ... NoReply`
在某些 GNOME/X11 系统上，Qt 在启动期间通过 DBus 探测桌面主题服务时可能会打印此警告。在大多数情况下，它是无害的，并且不会影响标尺的功能。
如果该警告反复出现，请检查你的会话 DBus 和 portal 服务（`dbus-daemon`、`xdg-desktop-portal`）是否正常运行。
## 贡献
1. 安装开发依赖项（与运行时依赖相同，另外加上 `pytest`）：
pip install -r requirements-dev.txt
2. 从代码库根目录运行测试套件：
pytest tests/
3. 纯逻辑辅助函数（`trace_ray`、`compute_edge_map`）是模块级函数，专门用于在没有显示器的情况下进行测试。尽可能以相同的风格编写新逻辑。
4. QML 覆盖层（`screen_ruler.qml`）和屏幕捕获代码需要运行中的 Qt 应用程序，因此不包含在单元测试范围内。
## 许可证
本项目基于 MIT 许可证授权。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
标签：OpenCV, PyQt6, Python, 屏幕尺, 无后门, 桌面工具, 漏洞挖掘, 边缘检测, 逆向工具