================================================================================ 画轨迹 · 折线绘制 · 开始虚拟轨迹 —— 详细教程 Drawing Routes, Polylines & Starting Virtual Playback — Step-by-Step Tutorial ================================================================================ 适用版本 / Version : 1.1.1 前置阅读 / First : USAGE.txt（安装、启动、连接 iPhone） 本文件纯文本、中英双语：中文在前，英文在后。 英文部分从第 652 行开始（搜「PART 2」可跳转）。 Plain text and bilingual: Chinese first, English second. English starts at line 652 (search for "PART 2" to jump there). ================================================================================ 第一部分：中文 ================================================================================ -------------------------------------------------------------------------------- 目录 -------------------------------------------------------------------------------- A. 开始之前：三件事必须先做完 B. 认识界面：每个按钮在哪、干什么 C. 地图基本操作 D. 三种造轨迹的方式 D1. 折线绘制（最直接，推荐先学这个） D2. 途经点 + OSRM 路线规划（最贴近真实道路） D3. 导入 GPX（复用别人/别的软件画好的轨迹） E. 编辑轨迹：撤销 / 删除 / 移动 / 排序 F. 出行模式与播放倍速 G. 真实感模拟参数逐个讲清楚 H. 开始虚拟轨迹播放 I. 播放过程中的控制：暂停 / 继续 / 拖进度 / 停止 J. 结束与恢复真实定位 K. 保存与复用路线 L. 快捷键总表 M. 常见问题与错误提示对照 N. 参数速查表 ================================================================================ A. 开始之前：三件事必须先做完 ================================================================================ 没做完这三件事，后面点「播放」一定会失败。请按顺序确认： A1. 设备已连接 顶部右上角的「连接设备」按钮点过了吗？ 点完之后，顶部中间的设备卡片会显示手机名称和 iOS 版本， 右上角的连接状态会从「未连接」变成已连接。 如果没变成，先看 USAGE.txt 的「常见问题」章节。 A2. 开发者镜像已挂载 iOS 17 及以上，虚拟定位依赖「开发者镜像」。 正常情况下点「连接设备」时会自动处理，不用你管。 如果日志里出现 "Failed to verify the disk image signature" 之类的报错， 手动点一次左下角的「挂载开发者镜像」按钮， 过程会实时输出到右侧「运行日志」面板。 A3. 手机放在手边，屏幕亮着 播放开始后，手机屏幕上会出现定位图标。 这是判断"到底有没有生效"最直接的证据，别把手机锁屏扔一边。 ── 做完这三件事，右侧运行日志里应该有类似这样的几行： [真机] DVT 虚拟定位会话已就绪（iOS 17+ / RSD ...，长连接保持中） [信息] 设备已连接：iPhone 11 看到「会话已就绪」就说明一切正常，可以开始画轨迹了。 ================================================================================ B. 认识界面：每个按钮在哪、干什么 ================================================================================ 界面分四块，从上到下、从左到右： ┌─────────────────────────────────────────────────────────────────────┐ │ 顶部工具条 │ │ 刷新设备 重新扫描 USB / 网络上的 iOS 设备 │ │ 连接设备 建立隧道 + 打开 DVT 定位会话（画轨迹前必须先点） │ │ 断开 释放会话，手机恢复真实定位 │ ├──────────────┬───────────────────────────────┬──────────────────────┤ │ 左：轨迹设置 │ 中：地图 │ 右：运行日志 │ │ │ │ │ │ 出行模式 │ ┌ 地图工具条 ─────────────┐ │ 出问题先看这里 │ │ 播放倍速 │ │ 选择 添加途经点 折线绘制 │ │ │ │ 真实感模拟 │ │ 撤销 删除选中点 全览 │ │ │ │ 路线概览 │ └─────────────────────────┘ │ │ │ 途经点列表 │ │ │ │ 底图/隧道 │ ┌ 状态标签 ───────────────┐ │ │ │ │ │ 未播放 进度 速度 坐标 │ │ │ │ 加载 OSRM │ └─────────────────────────┘ │ │ │ 清空 导入导出│ │ │ ├──────────────┴───────────────────────────────┴──────────────────────┤ │ 底部播放条 │ │ 播放 暂停 继续 停止 │ 进度条 │ 已用 剩余 序号 │ 实时速度 坐标 倍速 │ └─────────────────────────────────────────────────────────────────────┘ 记住三个最关键的位置，后面教程会反复用到： ① 地图工具条上的「折线绘制」 —— 画轨迹的入口 ② 左下角的「加载 OSRM 路线」 —— 用途经点生成真实道路路线 ③ 底部播放条上的「播放」 —— 开始虚拟轨迹 ================================================================================ C. 地图基本操作 ================================================================================ 这些操作在**任何**绘制模式下都可用： 拖拽 按住鼠标左键拖动 → 平移地图 缩放 滚轮上下滚 → 放大 / 缩小 全览 点工具条「全览」→ 自动缩放到刚好装下整条轨迹 切换底图 左侧「底图」下拉框 高德矢量（带标注，国内最清晰） 高德卫星（含路网标注） Esri 全球卫星（英文标注，全球可用） OSM（国内可能连不上） 查看坐标 鼠标在地图上移动，中间状态标签的「坐标」会实时跟着变 【一个很实用的技巧】先跳到学校/目标区域，再开始画 左侧「快速定位到坐标」输入框，填「纬度, 经度」然后点「跳转」。 例如： 30.2741, 120.1551 注意顺序是**纬度在前、经度在后**，用英文逗号或空格分隔。 跳转**只是把地图移过去**，不会改变手机定位 —— 放心点。 常用地点可以点「记住此地」存下来，下次在下拉框里选中，点「前往」直接过去。 ================================================================================ D. 三种造轨迹的方式 ================================================================================ 你可以用下面任意一种方式得到一条轨迹。三条路都能直接播放。 ┌──────────────┬────────────────────┬──────────────────┬──────────────┐ │ 方式 │ 适合场景 │ 路线是否贴合道路 │ 操作量 │ ├──────────────┼────────────────────┼──────────────────┼──────────────┤ │ D1 折线绘制 │ 操场绕圈、校园小路 │ 否（走直线） │ 最少，最快 │ │ D2 途经点 │ 马路跑步、真实通勤 │ 是（走真实道路） │ 中等 │ │ D3 导入 GPX │ 复用现成轨迹文件 │ 取决于文件 │ 最少 │ └──────────────┴────────────────────┴──────────────────┴──────────────┘ -------------------------------------------------------------------------------- D1. 折线绘制（最直接，推荐先学这个） -------------------------------------------------------------------------------- 这是最常用、最直观的方式：在地图上点一串点，连成一条线，然后让手机沿这条线跑。 【第 1 步】点工具条上的「折线绘制」 按钮会高亮，工具提示会变成： 「折线绘制中：点击加点，双击或 Esc 结束」 同时日志面板会输出： [信息] 开始折线绘制：连续点击地图加点，双击或 Esc 结束 ⚠️ 注意：进入折线绘制模式后，**双击放大被自动关掉了** —— 因为双击要用来"结束绘制"。想放大请用滚轮。 【第 2 步】在地图上依次点击 每点一下，就加一个轨迹点，地图上会立刻把已画的线段用橙色连起来。 工具提示会实时更新成： 「折线绘制中：已加 7 点，双击或 Esc 结束」 日志里每加一个点也会记一行，带精确坐标： [信息] 折线加点 7：116.397500, 39.908700 画的时候注意： · 点与点之间是**直线连接**，不会自动绕开建筑物 · 点越密，轨迹越贴合你想要的形状；但也没必要太密， 直线段中间的点对最终效果没有影响 · 拐弯处多点几个点，弧度会更自然 · 操场绕圈那种场景，绕一圈点 20~40 个点就够了 【第 3 步】结束绘制 三种方式任选： · 在最后一个点上**双击** · 按 键 · 点工具条上其它任意工具（比如「选择」），会自动结束 结束后会自动做三件事： 1. 地图自动缩放到刚好装下整条折线 2. 工具自动切回「选择」模式，双击缩放恢复 3. 弹出提示「折线绘制完成，可直接播放或导出 GPX」 ⚠️ 如果只点了 0 个或 1 个点就结束，会提示「折线至少需要 2 个点」， 这条折线会被丢弃。至少要 2 个点。 【第 4 步】检查一下 左侧「路线概览」区域现在应该有了数字： 总距离 例如 2.41 km 路径点数 你刚才点的点数 途经点 0（折线模式不走途经点） 路线引擎 直线（因为没走 OSRM） 状态标签的「轨迹点」也应该显示你的点数。 ✔ 到这里折线就画好了，可以直接跳到 H 节开始播放。 -------------------------------------------------------------------------------- D2. 途经点 + OSRM 路线规划（最贴近真实道路） -------------------------------------------------------------------------------- 折线走的是直线，会"穿墙过楼"。如果测试的是跑步 App，轨迹最好贴着真实马路， 这时候用途经点 + OSRM 路线规划。 【第 1 步】点工具条上的「添加途经点」 工具提示变成「添加途经点：在地图上点击添加」 【第 2 步】在地图上点选关键位置 不需要点很密 —— 只要点"路线要经过的地方"： 起点 → 第一个路口 → 拐弯处 → 途经的标志物 → 终点 一般 4~8 个点就够。点之间怎么走，交给 OSRM 去算。 【第 3 步】确认途经点列表 左侧「途经点列表」会出现你点的每一个点： 起 第一个点（绿色标记） 2 中间点 终 最后一个点 每一个点右边有按钮，鼠标移上去会显示： 定位到此处 把地图移到这个点 （还有删除按钮） 【第 4 步】点左下角的「加载 OSRM 路线」 这一步会**联网**请求 OSRM 路径规划服务，把点与点之间补成真实道路。 按钮会变成加载中状态，完成后： · 地图上的直线变成贴合道路的曲线 · 「路线引擎」从「直线」变成「OSRM」 · 「路径点数」会大幅增加（几百到几千，取决于距离） · 日志输出规划结果 ⚠️ 最少需要 2 个途经点，否则提示「至少需要 2 个途经点才能规划路线」。 ⚠️ OSRM 需要联网。连不上时会自动退化成直线连接， 路线仍然可用，只是不贴合道路。 【想调整路线怎么办】 调整途经点后，**必须重新点一次「加载 OSRM 路线」**， 否则地图上还是旧路线。 【微调途经点位置】 切到「选择」工具 → 在地图上**拖拽**途经点标记即可移动。 或者在左侧列表里**双击**某一行的坐标，直接输入精确经纬度。 【重新排序】 左侧途经点列表支持**拖拽排序** —— 抓住每行最左边的「⋮⋮」图标上下拖。 顺序变了之后同样要重新点「加载 OSRM 路线」。 -------------------------------------------------------------------------------- D3. 导入 GPX（复用现成轨迹） -------------------------------------------------------------------------------- 如果你已经有一条画好的轨迹（自己以前导出的、或者从别处拿到的 GPX 文件）， 直接导进来最省事。 【操作】 点左下角的「导入 GPX」→ 在弹出的文件选择框里选 .gpx 文件。 导入后，轨迹会同时填充到「途经点列表」里，你可以继续编辑。 【注意】 · 只支持 GPX（.gpx / .xml） · 点位很多的 GPX（比如几千个点）导入后会比较卡， 因为每个点都会变成列表里的一行 · 导入的轨迹不走 OSRM 重新规划，直接按文件里的点走 【导出】 点「导出 GPX」把当前轨迹存成 .gpx 文件， 可以拿去别的软件看，或者分享给别人。 ================================================================================ E. 编辑轨迹：撤销 / 删除 / 移动 / 排序 ================================================================================ 画错了不用从头再来。 撤销 点工具条「撤销」，或按快捷键。每点一次回退一步。 折线绘制完成时会自动存一个还原点， 所以"画完发现不对"可以直接撤销重画。 删除单个途经点 切到「选择」工具 → 在地图上点一下要删的点（会高亮）→ 点工具条「删除选中点」，或直接按 键。 也可以在左侧途径点列表里点该行的删除按钮。 移动途经点 切到「选择」工具 → 直接**拖拽**地图上的点标记。 修改精确坐标 左侧「途经点列表」里**双击**某一行的坐标文字 → 输入新的经纬度。 整体清空 点左下角的「清空」（红色文字那个），会清掉当前轨迹的全部点和路线。 这个操作**不可撤销**，想留着就先「保存」（见 K 节）。 缩放查看 点「全览」自动适配；手工缩放用滚轮。 ================================================================================ F. 出行模式与播放倍速 ================================================================================ 【出行模式】决定了轨迹的**基础速度**，也就是"手机以多快的速度移动"。 驾车 约 13.9 m/s（50 km/h） 骑行 约 5.5 m/s（20 km/h） 步行 约 1.4 m/s（5 km/h） 飞行 很快（适合大跨度场景） 切换模式后，「路线概览」里的「按速度预计」会立刻更新 —— 那是"按这个速度跑完全程要多久"。 【两个一键预设】懒人用法： 校园跑预设 步行 1.4 m/s、下发 10Hz、漂移 4m、浮动 ±8%、不循环 长跑预设 骑行 5.5 m/s、下发 10Hz、漂移 6m、浮动 ±10% 点了之后上面所有参数会被一次性设好，直接可以播。 校园跑 / 打卡类测试直接用「校园跑预设」就行。 【播放倍速】是**回放速度**，和出行模式是两回事： · 出行模式 = 手机"真实"移动多快（影响上报给 App 的速度） · 播放倍速 = 你多快看完这整条轨迹 1.0x 按真实时间播（2km 步行要跑 24 分钟） 10x 10 倍速，2km 只要 2.4 分钟 0.1x ~ 50x 可调范围，指数刻度 默认 1.0x ⚠️ 倍速调太高时，上报速度也会跟着变大， 有些 App 会认为"超出人类极限"而判定异常。 测跑步类 App，建议倍速不要超过 3~5x。 「路线概览」里的「按倍速播放」会显示当前倍速下大约要播多久。 【循环播放】 勾上「循环播放（到达终点后回到起点）」，跑到终点会自动回到起点继续， 适合长时间挂机测试。不勾则跑到终点自动停。 ================================================================================ G. 真实感模拟参数逐个讲清楚 ================================================================================ 这一组参数决定"轨迹看起来像不像真人跑出来的"。默认值已经比较合理， 刚开始可以完全不管，直接用默认值。下面解释每个参数到底在做什么。 ── G1. 定位漂移（默认勾选，半径默认 4 米） 现实中的 GPS 定位不是精确的点，而是在真实位置附近**缓慢游走**。 勾上这个，程序会让上报的坐标在设定半径内随机漂移。 半径怎么选： 4 米 一般手机在开阔地的水平精度，最自然，推荐 0 米 完全贴线走，轨迹会非常"完美"，反而假 10+ 米 手机信号差的环境（高楼间、树下），漂移明显 实现上是多尺度噪声（慢漂 + 中尺度 + 快抖）， 所以漂移是**平滑游走**的，不会出现瞬间跳变。 ── G2. 速度浮动（默认勾选，幅度默认 ±8%） 真人跑步不可能每秒钟都精确保持同一速度。 勾上后，瞬时速度会在设定值上下波动。 幅度怎么选： ±8% 自然的配速波动，推荐 ±20%+ 体力不支那种忽快忽慢 0% 精确匀速，一眼假 ── G3. 发送节奏抖动（默认勾选） 真实 GPS 上报不是"精确每秒一次"，而是有细微的时间抖动， 偶尔还会丢一两个采样点。勾上会更真实。 一般不用动它。 ── G4. 速度由位移推算（默认勾选） iOS 上报的速度不是独立字段，而是**由两个定位点之间的距离除以时间**算出来的。 勾上这个，程序也用同样方式推算速度， 保证「速度 / 位移 / 时间」三者自洽 —— 这是防作弊 App 最容易检查的地方。 建议保持勾选。 ── G5. 注入粗差跳点（默认不勾，概率默认 2%） 有时会故意上报一个明显偏离的坐标（比如突然跳到 30 米外）， 下一秒又跳回来。真实 GPS 偶尔确实会这样。 这个参数的用途是**测你自己 App 的过滤逻辑**： 如果你的 App 应该滤掉这种跳点，就打开它，看看滤不滤得掉。 平时测试**不要开**。概率建议 2%~5%，调高了轨迹会很难看。 ── 参数组合建议 测校园跑 / 打卡 → 直接用「校园跑预设」，或： 漂移 4m、浮动 ±8%、节奏抖动开、速度推算开、粗差关 测轨迹平滑算法 → 漂移调大（10~20m），看你的算法能不能平滑掉 测防作弊 / 过滤 → 粗差打开，概率 5%，看能不能识别 追求"最像真人" → 全部保持默认即可 ================================================================================ H. 开始虚拟轨迹播放 ================================================================================ 【前置检查】播放前请确认： ☑ 顶部设备卡片显示已连接，不是「未连接」 ☑ 右侧日志最后几行有「DVT 虚拟定位会话已就绪」 ☑ 地图上已经有轨迹（折线、OSRM 路线，或导入的 GPX 都行） ☑ 手机上「开发者模式」已开 ☑ 爱思助手 / i4Tools / Xcode 等同类工具已关闭 【第 1 步】设置参数 按 F、G 两节的说明把「出行模式」「播放倍速」「循环播放」 「真实感模拟」调好。第一次用可以什么都不动，直接用默认值。 【第 2 步】(可选) 给轨迹起个名字 左侧「轨迹名称」输入框，填一个记得住的名字，最多 60 字。 方便之后保存和复用。 【第 3 步】点底部的「播放」按钮 也可以直接按 <空格> 键。 如果一切正常，你会看到： · 底部「播放状态」从「未播放」变成正在播放 · 进度条开始从 0% 向右走 · 「已用 / 剩余」时间开始倒数 · 「序号」显示当前跑到第几个点，例如 137 / 4210 · 地图上的轨迹会被**逐段染成已播放的颜色**， 还有一个移动的标记跟着走 · 中间状态标签的「速度」「进度」「坐标」实时更新 · 右侧日志出现：「[信息] 开始播放：2.41 km，倍速 1.0x」 然后每隔一段时间输出「已下发 lat=..., lon=...（第 N 次）」 **最重要的一步**：看手机屏幕。 手机上的定位图标应该开始沿着你画的路线移动。 这是唯一能证明"真的生效了"的证据。 【第 4 步】确认手机真的动了 打开手机上的地图 App（高德 / 苹果地图都行）， 看蓝点是不是在按你画的路线走。 如果手机没动，先别急着调参数，去看 M 节的排查清单。 ── 播放失败时的常见提示 「请先添加至少 2 个途经点，或绘制折线、加载路线」 → 地图上还没有轨迹。回到 D 节先画一条。 「请先连接设备」 → 顶部没点「连接设备」，或者会话已经断了。 「设备响应超时，请检查连接后重试」 → DVT 连接断了（可能被别的工具抢了）。 点「断开」再点「连接设备」重连，然后重新播放。 ================================================================================ I. 播放过程中的控制 ================================================================================ 全部在底部播放条上。 ── 暂停 点「暂停」或按 <空格>。 手机**停在当前位置不动**（不会恢复真实定位）。 进度条和序号保留。 ── 继续 点「继续」，从暂停的位置接着播。 ── 跳转到任意位置（seek） 直接**拖动进度条**到想要的位置。 手机定位会立刻跳到轨迹上的对应点，然后从那里继续。 适合"我就想测第 3 公里那一段"。 ── 停止 点「停止」。播放结束，**手机立刻恢复真实定位**。 这跟「暂停」不一样 —— 暂停是停在虚拟位置，停止是回到真实位置。 ── 播放中实时看到的数字 底部右侧三格： 实时速度 当前上报给手机的速度（m/s 或 km/h） 当前坐标 当前下发到手机的经纬度 倍速 当前播放倍速 中间状态标签： 未播放/播放中 播放状态 进度 百分比 速度 同上 坐标 鼠标所在位置的坐标（注意：这个跟着鼠标走，不是播放位置） 轨迹点 总点数 ── 播放中改参数会怎样？ 大部分真实感参数（漂移、浮动等）在 `play.start` 时就一起下发了， 播放中改滑块**不会**立刻影响正在播放的这次。 要让它生效，停止后重新点「播放」。 播放倍速同理 —— 停止重播才会用新的倍速。 ================================================================================ J. 结束与恢复真实定位 ================================================================================ 有三种情况会让手机恢复真实定位，任何一种都可以： 1. 点底部「停止」 2. 点左下角的「恢复真实定位」按钮 3. 点顶部的「断开」，或直接关掉程序 ⚠️ 程序关闭时会自动恢复真实定位，**不会**把手机卡在虚拟位置。 万一遇到程序崩溃没恢复，重新打开程序点一次「恢复真实定位」即可。 ⚠️ 但有一种情况恢复不了：DVT 会话被别的工具挤断了。 这时候虚拟定位本身也已经失效，手机通常会自动回到真实位置。 如果手机还停在虚拟位置，重启一次手机就能恢复。 ================================================================================ K. 保存与复用路线 ================================================================================ 画一条满意的轨迹不容易，可以存起来反复用。 【保存到本地】 左侧「本地保存的路线」下拉框旁边： · 点「保存」→ 当前轨迹存进浏览器 localStorage · 点「载入」→ 载入下拉框里选中的那条 · 点「删除」→ 删掉选中的那条 · 也可以直接**双击**下拉框快速载入 ⚠️ 存在浏览器的 localStorage 里，所以： · 换浏览器 / 清浏览器数据 / 换电脑 → 路线会丢 · 想长期保存请用「导出 GPX」存成文件 【导出成文件】 点「导出 GPX」，得到一个 .gpx 文件。 这是跨机器、跨软件最可靠的保存方式。 【复用流程】 下次打开程序 → 点「导入 GPX」选那个文件 → 直接播放。 ================================================================================ L. 快捷键总表 ================================================================================ ┌────────────┬──────────────────────────────────────────┐ │ 按键 │ 作用 │ ├────────────┼──────────────────────────────────────────┤ │ 空格 │ 播放 / 暂停 │ │ Esc │ 结束折线绘制 │ │ Del │ 删除当前选中的途经点 │ │ Backspace │ 同上 │ │ 双击 │ 折线绘制中 = 结束绘制；其它模式 = 放大 │ └────────────┴──────────────────────────────────────────┘ 提示：焦点在输入框里时，空格键会输入空格而不会播放。 点一下地图空白处再按空格。 ================================================================================ M. 常见问题与错误提示对照 ================================================================================ ── 画轨迹相关 Q: 点「折线绘制」后点地图没反应 · 确认工具条上「折线绘制」是**高亮**状态 · 确认点的是地图区域，不是左侧面板 · 看日志有没有「折线加点 N」—— 有就说明点上了，只是视觉没看出来 Q: 双击想放大，结果结束了绘制 这是设计如此。折线绘制模式下双击 = 结束绘制，放大请用滚轮。 想放大又不想结束，先按 Esc 结束绘制，再双击放大。 Q: 提示「折线至少需要 2 个点」 你只点了 0 或 1 个点就结束了。至少点 2 个。 Q: 点「加载 OSRM 路线」没反应 / 还是直线 · 途经点少于 2 个 · 网络连不上 OSRM 服务（会自动退化成直线，日志里会有说明） · 改了途经点顺序后忘了重新点这个按钮 Q: 导入 GPX 后界面很卡 文件点数太多（几千个），每个点都会渲染成列表的一行。 可以用文本编辑器把 GPX 抽稀后再导入，或者改用折线绘制。 ── 播放相关 Q: 点「播放」没反应，提示要"添加至少 2 个途经点" 地图上还没有轨迹。先用 D1 / D2 / D3 任意一种方式造一条。 Q: 播放了，但手机定位没动 按顺序排查： 1) 手机屏幕上有没有出现定位图标？没有 → 会话没建立，重连设备 2) 右侧日志有没有「已下发 lat=..., lon=...」？没有 → 播放没真正开始 3) 日志里最后一次下发的坐标，是不是你轨迹上的点？ 4) 手机上的地图 App 打开看看，蓝点在不在动 5) 部分 App 有独立定位源（比如蓝牙 GPS），不受系统定位影响 6) 手机是不是被别的工具连着（爱思助手等），抢走了 DVT 连接 Q: 播到一半手机定位跳回真实位置 Windows 的用户态隧道偶尔会静默断开。 · 程序有保活：设了点但没在播放时每 15 秒重发一次 · 播放中断开的话，点「断开」→「连接设备」重连，再重新播放 · 长距离测试建议勾上「循环播放」，播放中连接更稳定 Q: 播放速度和我设的不一样 · 检查「播放倍速」（1.0x 才是真实时间） · 检查「出行模式」—— 它决定了基础速度 · 「实时速度」显示的是**上报给手机的速度**， 和"你看到轨迹移动的快慢"（受倍速影响）是两回事 Q: 拖进度条后手机没跟着跳 seek 需要一点时间下发，等 1~2 秒。 如果一直不动，说明连接断了，重连后重试。 Q: 停止后手机定位没恢复 点一次左下角「恢复真实定位」。 还不行就点「断开」，或者重启手机（一定有效）。 ================================================================================ N. 参数速查表 ================================================================================ ┌──────────────────────┬──────────────┬────────┬────────────────────────┐ │ 参数 │ 位置 │ 默认 │ 建议 │ ├──────────────────────┼──────────────┼────────┼────────────────────────┤ │ 出行模式 │ 左侧第一块 │ 驾车 │ 按 App 类型选；跑步选 │ │ │ │ │ 步行 / 骑行 │ │ 播放倍速 │ 左侧 │ 1.0x │ 跑步类 ≤ 3~5x │ │ 循环播放 │ 左侧 │ 关 │ 长时间挂机测试时开 │ │ 定位漂移 │ 真实感模拟 │ 开 4m │ 4m（开阔地） │ │ 速度浮动 │ 真实感模拟 │ 开 ±8% │ ±8% │ │ 发送节奏抖动 │ 真实感模拟 │ 开 │ 保持开 │ │ 速度由位移推算 │ 真实感模拟 │ 开 │ 保持开（防作弊关键） │ │ 注入粗差跳点 │ 真实感模拟 │ 关 2% │ 只在自己测过滤时开 │ │ 轨迹名称 │ 左侧 │ 空 │ 建议填，方便保存复用 │ └──────────────────────┴──────────────┴────────┴────────────────────────┘ 首次使用的最短路径： 点「校园跑预设」→ 画折线 → 点「播放」。 三个动作就能跑起来。 ================================================================================ 英文部分从下面开始 / English section starts below ================================================================================ ================================================================================ PART 2: ENGLISH ================================================================================ -------------------------------------------------------------------------------- Contents -------------------------------------------------------------------------------- A. Before you start: three must-dos B. UI overview: what every button does C. Basic map controls D. Three ways to create a route D1. Polyline drawing (simplest — start here) D2. Waypoints + OSRM routing (follows real roads) D3. Import a GPX file E. Editing a route: undo / delete / move / reorder F. Travel mode and playback speed G. The realism parameters, explained one by one H. Starting virtual playback I. Controls during playback: pause / resume / seek / stop J. Finishing and restoring the real location K. Saving and reusing routes L. Keyboard shortcuts M. Troubleshooting and error messages N. Parameter quick-reference table ================================================================================ A. Before you start: three must-dos ================================================================================ Skip any of these and "Play" will fail. Check them in order: A1. The device is connected Have you clicked "Connect device" (top-right)? Once it succeeds, the device card in the middle of the top bar shows the phone name and iOS version, and the connection pill changes from "not connected". If it doesn't, see the Troubleshooting section of USAGE.txt. A2. The developer disk image is mounted On iOS 17+ virtual location depends on the developer disk image. This is normally handled automatically when you click "Connect device". If the log shows something like "Failed to verify the disk image signature", click "Mount developer image" (bottom of the left panel) manually — progress streams into the "Run log" panel on the right. A3. The phone is next to you with the screen on Once playback starts a location arrow appears on the phone. That is the most direct evidence that it is actually working — don't lock it and walk away. -- When all three are done, the run log should contain lines like: [真机] DVT 虚拟定位会话已就绪（iOS 17+ / RSD ...，长连接保持中） [信息] 设备已连接：iPhone 11 Seeing "session ready" means everything is fine. Start drawing. ================================================================================ B. UI overview: what every button does ================================================================================ The window has four regions: +---------------------------------------------------------------------+ | Top bar | | Refresh devices rescan USB / network for iOS devices | | Connect device build the tunnel + open the DVT session | | (required before drawing) | | Disconnect release the session, restore the real location | +--------------+-------------------------------+----------------------+ | LEFT | CENTER: map | RIGHT: run log | | Route setup | | | | | +- Map toolbar -------------+ | Check here first | | Travel mode | | Select Add waypoint | | when anything fails | | Speed | | Polyline | | | | Realism | | Undo Delete point Fit | | | | Route stats | +---------------------------+ | | | Waypoints | | | | Basemap | +- Status chips -----------+ | | | | | idle progress speed | | | | Build OSRM | | coords track points | | | | Clear/Import | +---------------------------+ | | +--------------+-------------------------------+----------------------+ | Bottom playback bar | | Play Pause Resume Stop | progress | elapsed remaining index | | live speed | current coords | speed multiplier | +---------------------------------------------------------------------+ Remember these three locations; the tutorial uses them constantly: (1) "Polyline" on the map toolbar — how you draw a route (2) "Build OSRM route" (bottom-left) — turns waypoints into real roads (3) "Play" on the bottom playback bar — starts virtual playback ================================================================================ C. Basic map controls ================================================================================ These work in every drawing mode: Pan hold left mouse button and drag Zoom mouse wheel up / down Fit click "Fit" on the toolbar to frame the whole route Basemap "Basemap" dropdown on the left: AMap vector (with labels — clearest in China) AMap satellite (with road overlay) Esri world imagery (English labels, global) OSM (may be unreachable from mainland China) Coordinates move the mouse over the map; the "coords" chip follows it [Very useful tip] Jump to your target area before drawing Use "Jump to coordinates" in the left panel: type "latitude, longitude" and click "Go". For example: 30.2741, 120.1551 Order is latitude first, then longitude, separated by a comma or space. Jumping only moves the map — it does not change the phone's location, so it is completely safe to click around. Click "Remember this place" to save a spot; pick it from the dropdown and click "Go" next time. ================================================================================ D. Three ways to create a route ================================================================================ +--------------+--------------------+------------------+--------------+ | Method | Best for | Follows roads? | Effort | +--------------+--------------------+------------------+--------------+ | D1 Polyline | tracks, campus | No (straight) | Lowest | | D2 Waypoints | street running, | Yes (real roads) | Medium | | | real commutes | | | | D3 GPX | reusing an | Depends on file | Lowest | | | existing track | | | +--------------+--------------------+------------------+--------------+ -------------------------------------------------------------------------------- D1. Polyline drawing (simplest — start here) -------------------------------------------------------------------------------- The most direct method: click a series of points on the map to form a line, then let the phone travel along it. [Step 1] Click "Polyline" on the map toolbar The button highlights and the hint changes to: "Polyline drawing: click to add, double-click or Esc to finish" The log also prints: [info] start polyline: click repeatedly to add points, double-click or Esc to end NOTE: entering polyline mode disables double-click zoom, because double-click is used to finish the drawing. Use the wheel to zoom instead. [Step 2] Click points on the map one by one Every click adds a track point and the line is drawn immediately in orange. The hint updates live: "Polyline drawing: 7 points added, double-click or Esc to finish" Each point is also logged with its exact coordinates: [info] polyline point 7: 116.397500, 39.908700 While drawing: - Segments are straight lines; they do not route around buildings - More points = a shape that follows your intent more closely, but there is no need to overdo it — extra points along a straight segment change nothing - Add a few extra points at curves so the corners look natural - For a loop around a track, 20-40 points is plenty [Step 3] Finish the drawing Any of these: - Double-click on the last point - Press - Click any other tool (e.g. "Select") — drawing ends automatically Finishing does three things: 1. The map zooms to frame the whole line 2. The tool switches back to "Select" and double-click zoom is restored 3. A toast appears: "Polyline complete — you can play it or export GPX" NOTE: with 0 or 1 points you get "a polyline needs at least 2 points" and the line is discarded. Two points minimum. [Step 4] Sanity check The "Route overview" block on the left should now show numbers: Total distance e.g. 2.41 km Path points the number you just clicked Waypoints 0 (polyline mode does not use waypoints) Route engine Straight line (OSRM was not used) The "track points" chip should match too. Done — you can jump straight to section H to start playback. -------------------------------------------------------------------------------- D2. Waypoints + OSRM routing (follows real roads) -------------------------------------------------------------------------------- A polyline goes straight and will cut through buildings. If you are testing a running app, the track should hug real streets — use waypoints plus OSRM. [Step 1] Click "Add waypoint" on the map toolbar [Step 2] Click the key positions on the map You do not need many points — only the places the route must pass through: start -> first junction -> the turn -> a landmark -> finish Four to eight points is usually enough. OSRM fills in the path between them. [Step 3] Check the waypoint list The "Waypoint list" on the left now shows every point: Start the first point (green marker) 2 intermediate points End the last point Hovering a row reveals its buttons: "Center here" and delete. [Step 4] Click "Build OSRM route" (bottom-left) This makes a network request to the OSRM routing service and replaces the straight lines with real roads. When it finishes: - The straight lines become road-following curves - "Route engine" changes from "straight" to "OSRM" - "Path points" jumps to hundreds or thousands - The log prints the result NOTE: at least 2 waypoints are required, otherwise you get "at least 2 waypoints are needed to plan a route". NOTE: OSRM needs network access. If it is unreachable the app falls back to straight lines automatically — the route still works, it just won't follow roads. [Adjusting the route] After changing waypoints you MUST click "Build OSRM route" again, otherwise the map still shows the old route. [Fine-tuning waypoint positions] Switch to the "Select" tool and drag the markers on the map. Or double-click a row's coordinates in the left list and type exact values. [Reordering] The waypoint list supports drag-and-drop — grab the "||" handle on the left of a row and move it. Reorder, then click "Build OSRM route" again. -------------------------------------------------------------------------------- D3. Import a GPX file -------------------------------------------------------------------------------- If you already have a prepared track (something you exported earlier, or a file from elsewhere), importing is the least work. [How] Click "Import GPX" (bottom-left) and choose a .gpx file. The track also populates the waypoint list, so you can keep editing it. [Notes] - Only GPX (.gpx / .xml) is supported - A GPX with thousands of points will feel sluggish, because every point becomes a row in the list - Imported tracks are not re-routed through OSRM; the file's own points are used [Export] Click "Export GPX" to save the current track as a .gpx file you can open in other software or share. ================================================================================ E. Editing a route: undo / delete / move / reorder ================================================================================ You do not have to start over when you make a mistake. Undo Click "Undo" on the toolbar, or use the shortcut. One step per click. Finishing a polyline stores a restore point, so "drew it wrong" can simply be undone. Delete a single waypoint Switch to "Select", click the point on the map to highlight it, then click "Delete point" or press . You can also use the delete button on the row in the left list. Move a waypoint Switch to "Select" and drag the marker on the map. Edit exact coordinates Double-click the coordinate text on a row in the waypoint list. Clear everything Click "Clear" (red text, bottom-left). This removes all points and the route. It CANNOT be undone — click "Save" first if you want to keep it (section K). Zoom to view Click "Fit" to auto-frame, or use the wheel. ================================================================================ F. Travel mode and playback speed ================================================================================ [Travel mode] sets the BASE speed — how fast the phone "really" moves. Driving ~13.9 m/s (50 km/h) Cycling ~5.5 m/s (20 km/h) Walking ~1.4 m/s (5 km/h) Flight very fast (good for long distances) Switching mode instantly updates "Estimated at this speed" in the route overview — that is how long the route takes at that speed. [Two one-click presets] Campus run walking 1.4 m/s, 10 Hz, drift 4 m, jitter +-8%, no loop Long run cycling 5.5 m/s, 10 Hz, drift 6 m, jitter +-10% Clicking one sets everything above at once. For check-in / campus-run style testing, just use "Campus run". [Playback speed] is the PLAYBACK RATE — a different thing entirely: - Travel mode = how fast the phone "really" moves (affects reported speed) - Playback speed = how fast you watch the whole route 1.0x real time (a 2 km walk takes 24 minutes) 10x 10x faster, so 2.4 minutes 0.1x - 50x adjustable, exponential scale Default 1.0x NOTE: at high multipliers the reported speed scales up too, and some apps flag that as superhuman. For running apps keep it at 3-5x or below. "Playback at this multiplier" in the route overview shows the approximate duration at the current multiplier. [Loop] Tick "Loop (return to start after the end)" and playback restarts from the beginning when it reaches the end — handy for long unattended tests. Leave it off and playback stops at the end. ================================================================================ G. The realism parameters, explained one by one ================================================================================ These decide whether the track looks like a real person produced it. The defaults are sensible; you can ignore them entirely at first. -- G1. GPS drift (on by default, radius 4 m) Real GPS is not a precise point; it wanders slowly around the true position. With this on, reported coordinates drift randomly within the chosen radius. 4 m typical phone accuracy in the open — most natural, recommended 0 m perfectly on the line; looks too clean, and therefore fake 10+ m poor signal (downtown, under trees) It uses multi-scale noise (slow wander + medium + fast jitter), so the drift is a smooth wander rather than sudden jumps. -- G2. Speed jitter (on by default, +-8%) A real runner cannot hold exactly the same pace every second. With this on the instantaneous speed fluctuates around the set value. +-8% natural pace variation, recommended +-20%+ visibly tiring, speeding up and slowing down 0% perfectly constant — obviously synthetic -- G3. Timing jitter (on by default) Real GPS does not report exactly once per second; intervals vary slightly and samples are occasionally dropped. This makes that realistic. Usually no need to touch it. -- G4. Derive speed from displacement (on by default) iOS does not report speed as an independent field — it is computed as the distance between two fixes divided by the time between them. With this on the app computes speed the same way, keeping speed / displacement / time mutually consistent. That is the first thing a cheat-detecting app will check. Leave it on. -- G5. Inject gross errors (off by default, 2% probability) Occasionally reports a coordinate clearly off the line (say 30 m away) and then snaps back the next second. Real GPS does this sometimes. The purpose is to TEST YOUR OWN APP'S FILTERING: if your app is supposed to discard such jumps, turn this on and see whether it does. For normal testing keep it OFF. 2-5% is plenty; higher makes the track ugly. -- Suggested combinations Campus run / check-in -> use the "Campus run" preset, or: drift 4 m, jitter +-8%, timing on, derive on, gross off Testing smoothing -> raise drift (10-20 m) and see if your algorithm copes Testing anti-cheat -> gross errors on at 5%, see if it gets detected "Most realistic" -> keep every default ================================================================================ H. Starting virtual playback ================================================================================ [Pre-flight checklist] [ ] The device card at the top shows connected, not "not connected" [ ] The run log ends with "DVT session ready" [ ] A route exists on the map (polyline, OSRM route or imported GPX) [ ] Developer Mode is enabled on the phone [ ] 3uTools / i4Tools / Xcode and similar are closed [Step 1] Set the parameters Configure travel mode, playback speed, loop and realism per sections F and G. For a first run you can leave everything at its default. [Step 2] (Optional) Name the route Type a memorable name in "Route name" (max 60 characters) so it is easy to save and reuse later. [Step 3] Click "Play" on the bottom bar Or just press . If everything is fine you will see: - The playback state changes from idle to playing - The progress bar starts moving right from 0% - Elapsed / remaining times start counting - The index shows the current point, e.g. 137 / 4210 - The route on the map is progressively tinted as it plays, with a moving marker following it - The speed / progress / coords chips update live - The log prints "[info] playback started: 2.41 km, speed 1.0x" and then "sent lat=..., lon=... (N)" periodically MOST IMPORTANT: look at the phone. The location arrow should start moving along the route you drew. That is the only proof it actually works. [Step 4] Confirm the phone really moves Open a map app on the phone (AMap or Apple Maps) and watch the blue dot travel along your route. If the phone does not move, do not start tweaking parameters — go to the troubleshooting list in section M. -- Common failure messages "Please add at least 2 waypoints, or draw a polyline, or load a route" -> There is no route on the map yet. Go back to section D. "Please connect a device first" -> "Connect device" was not clicked, or the session dropped. "Device response timed out, check the connection and retry" -> The DVT connection dropped (possibly taken over by another tool). Click "Disconnect", then "Connect device", then play again. ================================================================================ I. Controls during playback ================================================================================ All on the bottom playback bar. -- Pause Click "Pause" or press . The phone STAYS at its current virtual position (it does not restore the real one). Progress and index are preserved. -- Resume Click "Resume" to continue from where you paused. -- Seek Drag the progress bar to any position. The phone jumps to the corresponding point on the route and continues from there. Handy for "I only want to test the third kilometre". -- Stop Click "Stop". Playback ends and the phone IMMEDIATELY returns to its real location. This differs from Pause: pause leaves it at the virtual position, stop restores the real one. -- Live numbers Bottom-right three cells: Live speed current speed reported to the phone (m/s or km/h) Current coords coordinates currently sent to the phone Multiplier current playback speed multiplier Status chips in the middle: idle / playing playback state progress percentage speed same as live speed coords the MOUSE position, not the playback position track points total point count -- What if I change parameters mid-playback? Most realism parameters are sent with `play.start`, so moving a slider during playback does NOT affect the run in progress. To apply them, stop and click Play again. The same applies to playback speed — stop and restart to use the new value. ================================================================================ J. Finishing and restoring the real location ================================================================================ Any of these restores the phone's real location: 1. Click "Stop" on the bottom bar 2. Click "Restore real location" (bottom-left) 3. Click "Disconnect" at the top, or simply close the app NOTE: closing the app restores the real location automatically — the phone is never left stuck at a fake position. If the app ever crashes without restoring, just reopen it and click "Restore real location". NOTE: one case cannot be recovered — when another tool evicts the DVT session. Virtual location is already dead at that point and the phone usually returns to its real position by itself. If it is still stuck, restart the phone. ================================================================================ K. Saving and reusing routes ================================================================================ A good route is worth keeping. [Save locally] Next to the "Saved routes" dropdown on the left: - "Save" stores the current route in browser localStorage - "Load" loads the selected entry - "Delete" removes the selected entry - You can also double-click the dropdown to load quickly NOTE: this lives in the browser's localStorage, so switching browsers, clearing site data, or moving to another machine loses it. For long-term storage use "Export GPX" to write a file. [Export to a file] Click "Export GPX" to get a .gpx file — the most portable way to keep a route. [Reusing] Next time: "Import GPX", pick the file, hit Play. ================================================================================ L. Keyboard shortcuts ================================================================================ +------------+-------------------------------------------------+ | Key | Action | +------------+-------------------------------------------------+ | Space | Play / Pause | | Esc | Finish polyline drawing | | Del | Delete the selected waypoint | | Backspace | Same as Del | | Double-clk | In polyline mode: finish; otherwise: zoom in | +------------+-------------------------------------------------+ Tip: when the focus is inside a text input, Space types a space instead of playing. Click an empty part of the map first. ================================================================================ M. Troubleshooting and error messages ================================================================================ -- Drawing Q: Clicking the map does nothing in polyline mode - Make sure "Polyline" is highlighted on the toolbar - Make sure you are clicking the map, not the left panel - Check the log for "polyline point N" — if it is there, clicks are registering Q: I double-clicked to zoom but it finished the drawing instead That is by design. In polyline mode double-click means "finish". Use the wheel to zoom, or press Esc first. Q: "A polyline needs at least 2 points" You finished with 0 or 1 points. Add at least two. Q: "Build OSRM route" does nothing / the line stays straight - Fewer than 2 waypoints - OSRM is unreachable (the app falls back to straight lines and says so in the log) - You reordered waypoints but forgot to click the button again Q: The UI lags after importing a GPX Too many points (thousands); each one becomes a list row. Decimate the GPX in a text editor, or use polyline drawing instead. -- Playback Q: Clicking "Play" does nothing but asks for "at least 2 waypoints" There is no route on the map. Create one with D1 / D2 / D3 first. Q: It plays but the phone's location does not move Check in order: 1) Does a location arrow appear on the phone? No -> session is not up; reconnect the device 2) Does the log show "sent lat=..., lon=..."? No -> playback never really started 3) Is the last sent coordinate on your route? 4) Open a map app on the phone — is the blue dot moving? 5) Some apps use an independent location source (e.g. a Bluetooth GPS) and ignore the system location 6) Is another tool (3uTools etc.) holding the DVT connection? Q: Halfway through, the phone reverts to its real location The Windows userspace tunnel occasionally drops silently. - The app has a keepalive: when a location is set but playback is stopped, it re-sends every 15 seconds - If it drops mid-playback, click "Disconnect" then "Connect device", then play again - For long routes, enable "Loop" — the connection is more stable while actively playing Q: The playback speed is not what I set - Check the playback multiplier (only 1.0x is real time) - Check the travel mode — it sets the base speed - "Live speed" is what is reported TO THE PHONE; how fast the track visually moves is a separate thing controlled by the multiplier Q: Dragging the progress bar does not move the phone Seeking takes a moment to send — wait 1-2 seconds. If it never moves, the connection is down; reconnect and retry. Q: After Stop the phone did not restore Click "Restore real location" (bottom-left). If that fails, click "Disconnect", or restart the phone (always works). ================================================================================ N. Parameter quick-reference table ================================================================================ +----------------------+--------------+--------+---------------------------+ | Parameter | Location | Default| Recommendation | +----------------------+--------------+--------+---------------------------+ | Travel mode | left, top | Driving| Match your app; walking | | | | | or cycling for running | | Playback multiplier | left | 1.0x | <= 3-5x for running apps | | Loop | left | Off | On for long unattended | | GPS drift | realism | On 4 m | 4 m (open sky) | | Speed jitter | realism | On +-8%| +-8% | | Timing jitter | realism | On | Leave on | | Derive speed | realism | On | Leave on (anti-cheat key) | | Gross errors | realism | Off 2% | Only when testing filters | | Route name | left | empty | Fill it in for reuse | +----------------------+--------------+--------+---------------------------+ Shortest path for a first run: Click "Campus run preset" -> draw a polyline -> click "Play". Three actions and it runs. ================================================================================ 链接 / Links ================================================================================ 仓库 / Repo : https://github.com/jbjf6666/ios-location-track 使用说明 : USAGE.txt（安装 / 连接设备 / 常见问题） Windows 文档 : docs/README-WINDOWS.md（中） / README-WINDOWS.en.md（英） 问题反馈 : https://github.com/jbjf6666/ios-location-track/issues ================================================================================