WT Map Distance

一个面向《战争雷霆》陆战的独立小地图测距工具。按下游戏中的小队标记键后，程序识别小地图里的玩家位置和新增或移动的黄色感叹号，计算两者距离，并通过置顶透明提示显示结果。

本项目是非官方第三方工具，与 Gaijin Entertainment 无关。程序只处理屏幕截图和全局热键，不读取游戏内存，不连接 localhost:8111，也不会拦截按键。

功能

• 可录制自定义小队标记键，默认是 Ctrl+V。
• 自动识别黄色感叹号和玩家箭头。
• OCR 识别小地图比例尺，也可强制使用手动比例尺和网格间距。
• 提示框支持预览、拖动、缩放，并持久化位置和大小。
• 可保存完整调试会话，并用脚本离线重放识别流程。
• 可打包为单个 Windows GUI 可执行文件，Tesseract OCR 会一并包含在程序中。

工作原理

1. 程序定期保存小地图基准帧。
2. 用户设置的小队标记键由 pynput 旁路监听，按键仍会原样传递给游戏。
3. 按键后在多个时间点截取小地图，以兼容标记图标出现的动画和延迟。
4. 图像处理只保留黄色 HSV 区域，再按尺寸、宽高比和轮廓特征筛选感叹号候选。
5. 程序比较按键前后的候选中心，寻找新增或发生有效位移的标记，并识别玩家的黄色或白色箭头。
6. Tesseract OCR 读取地图右下角的比例尺数值，OpenCV 检测比例尺横线或地图网格的像素长度。
7. 根据像素距离和比例换算实际距离，通过透明、置顶、鼠标穿透的 Qt 窗口显示结果。

系统要求

• Windows 10 或 Windows 11。
• 从源码运行需要 Miniconda、Anaconda 或其他可用的 Conda 安装。
• 游戏使用窗口化或无边框窗口模式。独占全屏可能导致桌面截图 API 获得黑屏。
• 当前识别逻辑面向陆战方形小地图。更改游戏分辨率、HUD 缩放或小地图尺寸后通常需要重新校准。

从源码运行

cd WTMapDistance
conda env create -f environment.yml
conda activate wt-map-distance
python app.py

使用方法

1. 启动游戏，并保持窗口化或无边框窗口模式。
2. 启动程序，点击“小队标记键”输入框，按下游戏中实际设置的小队标记键，然后保存设置。
3. 点击“测试当前地图”检查截图区域；预览应只包含右下角方形地图内部。
4. 如果区域有偏差，调整“左、上、宽、高”四个屏幕比例并保存。
5. 比例尺自动识别失败时，填写每格米数；点击“点击校准网格”，在相邻网格线上各点一次。需要完全忽略自动识别时，可分别勾选比例尺或网格间距旁的“强制使用”。
6. 点击“预览提示”，拖动提示框调整位置，拖动右下角调整大小；点击“完成调整”保存。
7. 回到游戏按下小队标记键。识别成功后，提示框会显示玩家到标记的距离。

配置保存在：

%LOCALAPPDATA%\WTMapDistance\config.json

调试会话

开启“保存每次标记的完整调试会话”后，每次有效的小队标记按键都会在以下目录创建一个独立会话：

%LOCALAPPDATA%\WTMapDistance\debug

每个会话可能包含：

• trace.json：设置、前台窗口、显示器和 DPI、截图延迟、识别候选、玩家位置、OCR 结果以及成功或失败阶段。
• baseline*.png：按键前的小地图、黄色掩码和候选标注图。
• after-120ms*、after-220ms*、after-350ms*：按键后的截图及中间识别结果。
• ocr-input.png、selected-annotated.png：OCR 输入和最终选择标注图，流程到达相应阶段时生成。
• debug-index.jsonl：位于调试根目录，汇总各次会话和结果。

使用当前代码离线重放会话：

python -s scripts/replay_debug.py "C:\Users\<用户名>\AppData\Local\WTMapDistance\debug\<会话目录>"

测试

运行测试：

python -s -m pytest -q tests

打包 Windows 可执行文件

python -s -m PyInstaller --noconfirm --clean WTMapDistance.spec

输出文件位于 dist\WTMapDistance.exe。

WTMapDistance.spec 是 PyInstaller 的构建配置，不是程序运行时配置。它指定 app.py 为入口、添加项目根目录搜索路径、声明 Windows 热键监听所需的隐藏导入，并从当前 Conda 环境中收集 Tesseract、相关 DLL 和英文 OCR 数据。因此，当前如需生成内置 OCR 的单文件程序，应使用 environment.yml 创建的 Conda 环境执行打包。这个文件经过项目定制，应提交到 Git，而 build 和 dist 目录不应提交。

项目结构

WTMapDistance/
├── app.py                 # 程序入口
├── wtmd/                  # 截图、识别、热键、界面和配置代码
├── scripts/               # 调试会话重放工具
├── tests/                 # 单元测试和视觉回归测试
├── environment.yml        # Conda 环境
├── requirements.txt       # pip 依赖
└── WTMapDistance.spec     # PyInstaller 构建配置

已知限制

• 默认区域以 2560 x 1600 和现有 HUD 比例为参考。其他分辨率使用归一化区域适配，但仍可能需要手动校准。
• 地图配色、HUD 主题、录制状态图标、缩放动画和游戏更新都可能影响视觉识别。
• 游戏独占全屏、截图保护或系统级叠加层可能影响截图和提示框显示。
• 屏幕识别具有延迟和误差，本工具不适合作为精密测量来源。

许可证

本项目使用 MIT License，详见仓库中的 LICENSE 文件。