LunaTranslator OCR 自动化执行方法四种截图触发机制与核心参数调优指南【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator 作为视觉小说Visual Novel翻译器其 OCR 文本源即“图像文字”输入方式需要以一定频率自动从游戏中截图并识别文字。由于不同游戏的文本刷新方式差异极大立即显示、逐字滚动、动态背景、live2D 等单一触发策略无法通用。本文以 docs/zh/ocrparam.md英文版见 docs/en/ocrparam.md、越南语版见 docs/vi/ocrparam.md为核心系统讲解 LunaTranslator 提供的“周期执行”“分析图像更新”“鼠标键盘触发等待稳定”三种自动化执行方式以及“文本相似度阈值”这一结果过滤机制并结合 src/LunaTranslator/textio/textsource/ocrtext.py、src/LunaTranslator/gui/setting/textinput_ocr.py 等源码逐一拆解每个参数的实际含义、默认值、取值范围与调优方向帮助你针对具体游戏选出最合适的截图触发策略。注本文以简体中文版文档为准其他语言版本的 docs/en/ocrparam.md、docs/vi/ocrparam.md 内容与之对应。为什么需要四种自动化执行方式不同游戏引擎渲染文本的方式完全不同有的游戏点击后文字立即整段出现文本速度最快有的游戏文字逐字打印、带有打字机效果还有的游戏存在动态背景、粒子特效或 live2D 立绘导致即使画面内容没变截取的图片也在持续变化。LunaTranslator 的 OCR 文本源需要判断“何时截图、何时执行 OCR、何时判定文本已更新”因此设计出多种触发策略来适配这些场景。从源码结构看这套逻辑集中在 OCR 文本源 ocrtext.py 中核心类ocrtext通过后台线程gettextthread()持续轮询见 ocrtext.py根据配置的自动化方法ocr_auto_method_v2分派到不同的判断分支而每个 OCR 区域的相似度状态由rangemanger类维护ocrtext.py保存了“上一次截图”savelastimg、“上一次执行 OCR 时的图像”savelastrecimg、上一次 OCR 时间lastocrtime以及上一次 OCR 文本savelasttext。在图形界面中自动化执行方式与参数面板位于 OCR 文本源的设置页由 textinput_ocr.py 中的“自动化执行方法”下拉框选择可选值包括分析图像更新analysis、周期执行period、鼠标键盘触发等待稳定trigger默认值为period选择后调用_ocrparam_create动态生成对应的参数行textinput_ocr.py。周期执行Periodic Execution工作原理“周期执行”是最简单、最稳妥的方式。它不关心图像内容是否变化只按照固定的“执行周期s”定时执行一次截图 OCR 翻译流程。在 getresauto() 中对应ocr_auto_method_v2 period的分支elif globalconfig.get(ocr_auto_method_v2, period) period: if time.time() - self.lastocrtime globalconfig.get(ocr_interval, 1.5): ok True else: ok False即每次进入判断时只要距离上一次执行 OCR 的时间超过了ocr_interval秒就直接执行 OCR。参数说明参数配置键默认值取值范围说明执行周期 (s)ocr_interval1.50.1 ~ 100两次 OCR 执行之间的最小时间间隔单位为秒支持小数对应的控件代码位于 textinput_ocr.pyD_getspinbox(0.1, 100, globalconfig, ocr_interval, doubleTrue, default1.5)。调优建议周期过大文本更新后要等待较久才会被识别翻译表现为“翻译滞后”。周期过小会频繁调用 OCR占用 CPU/GPU 资源若文本尚未变化还会因重复翻译触发文本相似度过滤见下文。该方式适合文本会持续变化、且你对其他参数不太熟悉的场景——正如文档中的提示如果无法理解其他设置中的参数请直接使用这种方式因为它最简单。分析图像更新Analyze Image Update这是参数最多、也最智能的一种方式。它通过比较连续截图之间的相似度来判定“画面是否稳定”和“文本是否真的发生了变化”避免在画面尚未稳定或文本没有变化时白白执行 OCR。在 getresauto() 中对应ocr_auto_method_v2 analysis的分支完整流程为截取当前图像与“上一次截图”savelastimg计算相似度image_score调用imgr1.MSSIM(self.savelastimg)即结构相似度指标 MSSIM底层实现在 CVUtils.py将image_score通过信号thresholdsett1实时显示到界面对应设置页的动态标签__label1见 textinput_ocr.py若image_score大于“图像稳定性阈值”ocr_stable_sim_v2判定画面已稳定进入下一步否则认为画面仍在变化本次不执行 OCR画面稳定后再与“上一次执行 OCR 时的图像”savelastrecimg注意不是上一次截图计算相似度image_score2并通过信号thresholdsett2显示若image_score2小于“图像一致性阈值”ocr_diff_sim_v2判定游戏文本已经发生变化执行 OCR并更新savelastrecimg否则认为文本没变跳过本次。图像稳定性阈值Image Stability Threshold参数配置键默认值取值范围说明图像稳定性阈值ocr_stable_sim_v20.50 ~ 1步进 0.001当前截图与上一次截图的相似度大于该值才认为画面处于稳定状态适用场景与调优对应源码 ocrtext.py当游戏文本不是立即出现文本速度不是最快、或者游戏有动态背景 / live2D时截取的图片会持续变化。此时需要设置一个阈值只有当画面“足够接近上一次”时才算稳定。如果能够确定游戏完全静态背景固定、无动画可以将该值设为0即任何相似度都被认为稳定加快判定速度反之游戏画面越“闹”该值越应适当调高避免把动态画面误判为稳定文本。界面中的实时相似度显示thresholdsett1信号可帮助你观察游戏画面的波动情况从而反推合理的阈值。图像一致性阈值Image Consistency Threshold参数配置键默认值取值范围说明图像一致性阈值ocr_diff_sim_v20.950 ~ 1步进 0.001画面稳定后当前图像与上一次执行 OCR 时图像的相似度小于该值才判定文本已变化并执行 OCR文档特别强调这个参数是最重要的。它的核心设计在于“和上一次执行 OCR 时的图像比较而不是和上一次截图比较”——这样即使背景动画一直在轻微变化只要文本区内容没变就不会反复触发 OCR。调优方向对应源码 ocrtext.py如果 OCR 频率过快文本没变也频繁翻译说明当前相似度常常低于阈值应适当提高该值让“文本变化”的判定更严格如果反应太过迟钝文本变了却不及时翻译则应适当降低该值让判定更敏感默认值 0.95 是通用的起点它要求当前画面与上次 OCR 画面有 5% 以上的差异才认为文本更新。鼠标键盘触发 等待稳定Mouse/Keyboard Trigger Wait for Stability触发事件Trigger Events默认情况下以下鼠标/键盘事件会触发该方法配置项ocr_trigger_events的默认值见 config.json按键vkeyevent 值含义鼠标左键LBUTTON0按下pressEnterENTER0按下pressCtrlCTRL1松开releaseAltALT1松开releaseShiftSHIFT1松开release注意默认事件中Ctrl / Shift / Alt 使用的是松开事件event 为 1而左键与 Enter 使用按下事件event 为 0——这通常是因为在游戏中“松开”组合键时才完成一次操作如 ADV 游戏中按住 Ctrl 快进后松开。若绑定了游戏窗口hwnd有效则只有当游戏窗口为前台窗口时才会触发该方法。源码中通过比较游戏窗口与当前前台窗口的线程进程 ID 来实现ocrtext.py并做了一定次数的等待重试。触发事件可在界面上通过“触发事件”按钮自定义对应 textinput_ocr.py 与事件编辑器triggereditor配置保存在ocr_trigger_events列表中每个事件包含vkey与event两个字段。触发后的等待流程触发方法后由于游戏需要时间渲染新文本文本速度不是最快时文字不会立即出现必须等待文本稳定后才执行 OCR。该流程对应 gettextthread() 中的trigger分支检测到触发事件后先等待固定延迟ocr_trigger_delay秒然后进入“等待稳定”循环通过waitforstablex()→rangemanger.waitforstable()ocrtext.py持续比对当前截图与上一次截图的相似度直到所有区域的相似度都超过“图像稳定性阈值”为止稳定后一定会执行翻译不再考虑文本相似度调用的是getallres(False)即手动模式直接返回结果。延迟 (s)Delay参数配置键默认值取值范围说明延迟 (s)ocr_trigger_delay00 ~ 100触发后固定的等待时间秒之后才进入稳定判定这里有一个重要细节即便将延迟设为 0系统中也内置了0.1 秒的固有延迟用于满足游戏引擎的内部逻辑处理如状态机更新、消息循环。若游戏文本速度为最快点击后立即整段显示则“延迟”和“图像稳定性阈值”都可以直接设为 0跳过固定等待、仅靠稳定判定快速执行。触发模式下的图像稳定性阈值参数配置键默认值取值范围说明图像稳定性阈值触发模式ocr_stable_sim2_v20.950 ~ 1步进 0.001当前截图与上一次截图的相似度大于该值才认为文本绘制完毕可以执行触发事件这个值与“分析图像更新”模式下的同名参数ocr_stable_sim_v2作用类似但它只用于判定文本是否绘制完毕因此与前者不共用配置——两个参数分别保存在不同的配置键中界面上也分别生成独立控件源码见 textinput_ocr.py通过(ocr_stable_sim_v2, ocr_stable_sim2_v2)[f trigger]选择对应的配置键。为什么需要它因为慢速文本逐字打印的绘制时间是不固定的仅靠固定的“延迟”可能不够有时文字还没打完固定延迟就已经结束。因此系统在固定延迟之后继续做图像稳定判定——当当前截图与上一次截图的相似度高于该阈值时说明画面不再变化、文本绘制完毕此时才真正执行本次触发事件对应 waitforstable() 的返回值判定。文本相似度阈值Text Similarity Threshold解决的问题OCR 结果本身是不稳定的图片的微小扰动抗锯齿抖动、光影变化、字体渲染差异经常导致识别出的文本出现微小变化如果每次都照单全收翻译就会被连带反复触发产生大量重复翻译。为此LunaTranslator 在每次 OCR 之后增加了一道文本级过滤。实现机制该参数适用于所有自动化执行方式位于getresauto()的最后一段ocrtext.pyresult ocr_run(imgr) t result.textonly self.lastocrtime time.time() sim NativeUtils.distance(self.savelasttext, t) self.savelasttext t if sim globalconfig.get(ocr_text_diff, 3): return self.savelasttext t return result具体逻辑为执行 OCR 得到本次文本t与上一次 OCR 的文本savelasttext计算编辑距离Levenshtein distance——底层调用 Native 实现NativeUtils.distanceNativeUtils.py通过levenshtein_distance计算两个字符串之间需要多少次插入/删除/替换才能相互转换只有当编辑距离大于“文本相似度阈值”ocr_text_diff时才输出文本进入翻译流程否则丢弃本次结果。参数说明参数配置键默认值取值范围说明文本相似度阈值ocr_text_diff30 ~ 100000本次 OCR 结果与上次 OCR 结果的编辑距离大于该值时才输出文本例如默认值 3 意味着当两次识别文本只差 1~2 个字符编辑距离 ≤ 3时视为“文本没实质变化”不触发重复翻译只有当差异足够大时才认为文本确实更新了。调优建议重复翻译过多说明文本微小扰动常被识别为差异应适当提高该值过滤更严格文本更新被漏掉例如新文本与旧文本在字符层面较为相似但语义已变或慢速文本逐字追加时每次只多一两个字可适当降低该值但注意过低的阈值会导致频繁重复翻译注意该过滤不适用于手动触发模式文档明确指出“鼠标键盘触发 等待稳定”方式在稳定后**一定会进行翻译不会考虑文本的相似度”调用getallres(False)ocrtext.py 中手动路径直接返回结果——因为玩家主动操作点击/按键本身就代表“要看下一句文本”的明确意图。四种方式的选择建议与整体工作流选择建议周期执行最简单的兜底方案。适合对参数不熟悉的用户或文本持续滚动、无固定节奏的游戏缺点是可能会做大量无效 OCR。分析图像更新最“智能”的自动方案。适合文本逐字出现、有动态背景/live2D、希望自动感知文本更新的游戏需要耐心调节稳定性阈值与一致性阈值两个参数。鼠标键盘触发 等待稳定延迟最低、最精准的方案。适合常规 ADV 游戏点击/按键推进文本触发即时、稳定后必翻译缺点是依赖固定的操作习惯文本自动滚动时无法触发。整体工作流回顾无论选择哪种方式OCR 文本源的完整处理链路是一致的以 ocrtext.py 为骨架截图imageCutEx按设定的 OCR 区域截取游戏画面ocrtext.py支持 GDI 截图、区域裁剪、可选的ocr_preprocess.py图像预处理触发判定根据ocr_auto_method_v2选择周期 / 图像分析 / 鼠标键盘触发三种策略之一决定本次是否执行 OCR执行 OCRocr_runocrutil.py调用当前选中的 OCR 引擎引擎列表见 ocrengines/识别文本文本过滤与上次 OCR 结果比较编辑距离过滤重复/微小变化翻译输出通过的文本进入翻译流程并显示。在实际使用中建议先以默认参数周期 1.5s / 稳定性阈值 0.5 / 一致性阈值 0.95 / 文本差异 3跑通流程再结合界面上的实时相似度显示阈值标签会实时展示当前 MSSIM 相似度逐步微调。每个游戏的画面特征与文本节奏都不同没有万能参数组合但理解了每个阈值“大于/小于即动作”的判定方向后就能根据“翻译太快/太慢/重复/漏译”等表现快速定位到对应参数。小结LunaTranslator 为 OCR 自动化截图提供了周期执行、分析图像更新、鼠标键盘触发等待稳定三种方式并统一叠加文本相似度阈值进行结果过滤对应配置键为ocr_auto_method_v2、ocr_interval、ocr_stable_sim_v2、ocr_diff_sim_v2、ocr_stable_sim2_v2、ocr_trigger_delay、ocr_text_diff全部配置存放在 defaultconfig/config.json 中并在运行期写入用户配置。图像级判定依赖 MSSIM 结构相似度CVUtils.py文本级判定依赖 Levenshtein 编辑距离NativeUtils.py两者都是成熟的通用指标判定方向均可总结为“大于阈值才动作 / 小于阈值才动作”的简单规则。“分析图像更新”中的稳定性阈值与“触发等待稳定”中的稳定性阈值是两个独立的配置ocr_stable_sim_v2与ocr_stable_sim2_v2作用时机与判定目的不同切勿混淆。若追求简单可靠请用周期执行若追求自动感知文本更新请用分析图像更新若追求即时精准响应请用鼠标键盘触发等待稳定。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考