purrrock/dtg1-map-tools
GitHub: purrrock/dtg1-map-tools
一套基于 ATS3085S 平台智能手表离线地图的逆向工程与自定义编译工具集，支持从 OpenStreetMap 数据编译地图并注入 GPX 路线。
Stars: 2 | Forks: 0
# 为 DT NO.1 G1 / VWAR / KKTICK / Amolde HD300 Pro 定制离线地图
**(ATS3085S 硬件平台，Zephyr RTOS 软件平台)**
🇷🇺 [Читать на русском](README_ru.md)
如果你正在寻找**如何将自定义地图安装到智能手表上**，或者需要更好的 **DT NO.1 G1 离线地图**以通过 **WearPro** 应用同步，本项目提供了一个完整的开源解决方案。
➡️ **[下载适用于 Windows 的现成编译器 (.EXE)]** [](https://github.com/purrrock/dtg1-map-tools/releases/latest)
这是一套 Python 工具集，用于对 DT NO.1 G1、VWAR、KKTICK 和 Amolde 智能手表（以及其他基于 Actions Semiconductor ATS3085S 硬件平台的白标设备）的自定义离线地图进行逆向工程、分析和编译。如果你正在寻找如何将自定义地图安装到智能手表上，或者需要更好的 DT NO.1 G1 离线地图以通过 WearPro 应用同步，本项目提供了一个完整的开源解决方案。
该工具集允许利用开源数据（例如 OpenStreetMap）构建你自己的高细节地图。这些自定义地图原生支持硬件加速，并能被手表内置的图形引擎完美渲染。
## 🚀 核心编译器功能
编译器进行了重大升级，以绕过固件的原生限制并优化资源消耗：
* **兴趣点 (POI) 图标烘焙：** 规避了硬件图形流水线的限制（该限制原生会丢弃 POI 渲染），通过参数化将点对象“烘焙”到 landuse 层中。生成低多边形几何基元（三角形、正方形、六边形），并带有自动的显示透视畸变补偿（Y 乘数 = 1.5）。
* **软件剔除（提前退出解析）：** 高度优化的双通道 XML 流处理 (`xml.etree.ElementTree.iterparse`)。在遍历树结构时，通过 LUT 配置中的第 11 列 (`Enabled`) 立即丢弃被禁用的路网节点。
* **动态硬件覆盖（标签拦截）：** 基于多维 OSM 标签动态覆盖标准的 LUT 路由规则。
* *路面分析：* 动态分析 `surface` 和 `smoothness` 标签。如果 `smoothness=bad` 或 `surface=dirt`，会自动将路网等级（例如主干道）降级为未铺砌的灰色路径。通过内部排除掩码，为非车辆基础设施（人行道、自行车道）保留原始的 LUT 颜色。
* *访问限制：* 具有访问限制 (`access=private/no/permit`) 的物理屏障会在 LUT 评估之前被拦截，并强制转换为粉色对角十字。
* **命名空间冲突隔离：** 黑名单注册表严格按层（`pois`、`roads`、`landuse`、`water`）进行隔离，以防止不同分类对象之间发生 `fclass` 路由冲突。
* **GPX 轨迹整合：** 将自定义的 `.gpx` 用户路线原生直接编译进硬件矢量图中。
* **高级键值对标签路由：** 完全解析 `features.csv` 中的 `OSM_Tags` 列以解决命名空间冲突。在应用回退启发式算法之前，使用精确的 `key=value` 哈希表查找（例如，`shop=bicycle -> bicycle_shop`）对对象进行严格路由。这确保了所有复杂的 GIS 类别都能在无数据丢失的情况下被编译。
## 📸 对比：原厂地图 vs. 自定义编译地图
| 原厂地图 | 自定义编译地图 | 带路线的自定义地图 | 带兴趣点 (POI) 的自定义地图 |
| :---: | :---: | :---: | :---: |
| 
| 
| 
| 
|
## 📂 工具包组成
为了更好的可维护性和隔离调试，本项目已过渡为完全的**模块化架构**。代码库与手表的硬件解析器保持 100% 的二进制兼容性，并包含：
* **`dtg1_map_compiler.py`** — 主 CLI 协调器。协调地图构建过程。
* **`dtg1_models.py`** — 数据结构和系统常量（`MapFeature`、`HWConfig`）。
* **`dtg1_osmparser.py`** — 地图和路线解析逻辑（`OSMParser`、`GPXParser`）。
* **`dtg1_geometry.py`** — 几何算法和 POI 烘焙（`POIGeometryFactory`）。
* **`dtg1_bin_writer.py`** — 针对目标文件的底层二进制序列化（`MapCompiler`）。
* **`dtg1_lookup.py`** — 高级 LUT 配置和标签路由（`LookupTables`）。
* **`features.csv`** — 可修改的样式路由表 (LUT)，支持软件剔除（黑名单）。
* **`features_factory.csv`** — 原厂样式表的原始转储。
* **`make_exe.cmd`** — 使用 PyInstaller 将项目编译成 Windows 独立 `.exe` 的批处理脚本。
* **`dtg1_map_specification.md`** — 技术格式规范。包含 `.mlp`、`.idx` 和 `.db` 文件的逐字节结构。
## ⛰️ 等高线（实验性社区工具）
感谢 XDA-Developers 社区的贡献，本仓库现在包含用于处理地形等高线的实验性实用工具（位于 `/contours` 目录中）。这些脚本允许你在编译之前，将高程 LineString 合并到你基础的 OpenStreetMap 数据中。
如果你使用等高线功能，必须配置你的 `features.csv`。请阅读 `/contours/README_contours.md`。
## 🛠 安装和快速入门
编译器现在既支持从 Python 源代码运行，也支持编译为独立的可执行文件！
### 选项 A：独立可执行文件（仅限 Windows）
非常适合普通用户。无需安装 Python！
1. 将 `dtg1_map_compiler.exe`、`features.csv` 文件以及你的源 `map.osm` 数据放入任意方便的文件夹中。
2. 通过命令行运行可执行文件（例如 `dtg1_map_compiler.exe -p landuse`）。
### 选项 B：从源代码运行（开发者 & 跨平台）
1. 确保你安装了 Python 3.8 或更高版本。核心地图构建不需要额外的第三方依赖项（本项目完全使用内置模块）。
2. 下载仓库及其所有模块化的 Python 文件。
### 标准编译工作流
1. 从 https://www.openstreetmap.org/export 以 XML 格式导出所需的地图区域。
2. 将下载的文件重命名为 `map.osm`，并将其放在编译器旁边的工作目录中。
3. 运行脚本：`python dtg1_map_compiler.py -p landuse`
4. 编译后的二进制文件（`roads.mlp`、`roads.idx`、`landuse.db`、`map.name` 等）将出现在当前目录中。
5. 将这些生成的文件复制到手表的内部存储器中（通常通过 USB 连接放入 `MAP/Map_Name` 文件夹）。
## ⚡ 预处理大型地图（强烈推荐）
如果你正在编译大面积区域、整个国家，或者在编译过程中遇到 PC 内存溢出 (Out-Of-Memory) 错误，你应该使用 `osm_optimizer.py` 实用程序预处理原始的 `.osm` 文件。智能手表的硬件存在限制。将极其漫长的连续线条（如主要高速公路）作为单个对象渲染，可能会导致手表 UI 卡死或触发软重置 (Soft Reset)。
优化器通过以下方式解决此问题：
1. **硬件安全的分块：** 将极长的线性路线安全地切割成较小的片段（例如，每个片段 100 个顶点），同时保留闭合多边形（湖泊、森林）的数学拓扑结构，以防止扫描线渲染故障。
2. **激进的元数据剥离：** 移除沉重的 OSM 元数据（时间戳、用户、变更集）并丢弃全局黑名单标签（例如，`power`、`building`、`addr:*`），以大幅减小中间文件的大小。
## ⚙️ 命令行界面 (CLI) 参数
编译器实现了对兴趣点 (POI) 层的管理，在当前的固件版本中，该层的输出会被 ATS3085S 图形引擎在硬件层面上抑制。
可用标志：
* `-h`、`--help` — 输出可用参数的参考信息。
* `-p MODE`、`--poi-mode MODE` — 兴趣点 (POI) 数据库的生成模式。
* `none`（默认）— 在构建期间完全忽略 POI。防止数据库膨胀。
* `native` — 生成原始的 `pois.idx` 和 `pois.db` 二进制文件。可用于测试固件反应。
* `landuse` — 通过动态形状烘焙将 POI 整合到 landuse 层中。
## 🎨 样式自定义和对象过滤
`features.csv` 文件（Look-Up Table，查找表）是编译器的主要配置文件。它会在每次启动时被动态加载。
### LUT 表结构（11 列）
配置由 11 列组成，以分号 (`;`) 分隔。
**标头格式：**
```
Code;fclass;Color;LOD;Layer;OSM_Tags;Description;Remap_Code;Remap_Color;Remap_LOD;Enabled;;Shape
```
**重映射（别名）参数尤为重要：**
* **Remap_Code：** 对象将被强制转换为成的系统 32 位 ID。
* *示例：* 铺砌好的道路被映射到黄色的颜色 ID 5113。
* **Remap_LOD：** 硬件 Z-Culling 隐藏距离（以米为单位），表示缩放时对象在屏幕上显示的距离。
### 软件剔除（黑名单）
为了保护手表的图形流水线免受 RAM 溢出和 `.idx` 二进制图膨胀的影响，在流解析阶段实现了软件剔除系统。配置的第 11 列 — `Enabled` — 负责过滤。
* `1`（或 `true`）— 对象被加载到编译器中并参与地图生成。
* `0`（或 `false`）— 静音类。被硬件剔除。算法利用提前退出解析中断：遇到带有 `Enabled=0` 值的标签时，解析器会在计算 Bounding Box 之前立即丢弃该 XML 节点。这节省了 CPU 时间，并防止了被排除的对象被替换为默认的灰色或绿色样式。
### 恢复出厂设置
通过逆向工程构建的原始样式表保存在参考文件 `features_factory.csv` 中。要将所有用户对颜色、黑名单和级别细节的修改恢复为默认值：
1. 删除当前已修改的工作文件 `features.csv`。
2. 复制一份 `features_factory.csv` 文件并将其重命名为 `features.csv`。
3. 运行构建脚本，使用出厂参数值重新编译二进制文件。
## 🗺️ 自定义路线注入 (GPX)
编译器支持在基础地图上直接注入导航轨迹。
1. 将你的路线文件 (`*.gpx`) 放入 `routes/` 目录。
2. 运行构建。脚本会自动找到轨迹并提取其名称。提取出的字符串被编译到 `roads.db` 属性数据库中，确保轨迹在手表上保留其原始名称。
3. 注入的 GPX 轨迹将被转换为特定类型 `5111`（高速公路/Motorway）的对象。此代码在手表固件中是为渲染粗体、高对比度的橙色线条而硬件保留的。为了防止计划路线与实际的高速公路混淆，源 OSM 文件中的所有高速公路对象都会通过 `features.csv` 中的代码替换，强制降级为黄色类型 `5112`（干道/Trunk）。
*注意：要禁用注入并构建干净的地图，只需在启动前删除 GPX 文件即可。*
## 🔬 逆向工程工具 (`/tools`)
本仓库包含了在对 ATS3085S 图形流水线进行逆向工程期间使用的内部脚本：
* `dtg1_idx_dumper.py` — 一个反编译器，将 `.idx` 空间索引提取为可读的 CSV 格式以进行二进制分析。
* `roads_fuzzer.py` — 生成几何基元的坐标网格，以测试硬件 Z-Index 渲染和 C-Union 结构限制。
## 🔮 路线图与未来计划 (v4.1+)
核心编译引擎现已稳定。我们的下一个主要目标是将这个 CLI 工具转化为面向智能手表社区的、用户友好的“地图即服务 (Map-as-a-Service)”平台。
* [ ] **预编译的地图包：** 定期更新、可直接下载的整个国家或热门旅游地区的地图包。这些将直接托管在 GitHub Releases 中 — 最终用户无需安装 Python。
* [ ] **基于 Web 的 GUI 生成：** 一个基于浏览器的界面，用户可以在其中选择自定义的 Bounding Box（最大 50x50 公里），切换特定的图层/POI，上传他们的 GPX 轨迹进行注入，并通过连接到 Overpass API 的后端按需编译地图。
| | | |
## 📂 工具包组成
为了更好的可维护性和隔离调试，本项目已过渡为完全的**模块化架构**。代码库与手表的硬件解析器保持 100% 的二进制兼容性，并包含：
* **`dtg1_map_compiler.py`** — 主 CLI 协调器。协调地图构建过程。
* **`dtg1_models.py`** — 数据结构和系统常量（`MapFeature`、`HWConfig`）。
* **`dtg1_osmparser.py`** — 地图和路线解析逻辑（`OSMParser`、`GPXParser`）。
* **`dtg1_geometry.py`** — 几何算法和 POI 烘焙（`POIGeometryFactory`）。
* **`dtg1_bin_writer.py`** — 针对目标文件的底层二进制序列化（`MapCompiler`）。
* **`dtg1_lookup.py`** — 高级 LUT 配置和标签路由（`LookupTables`）。
* **`features.csv`** — 可修改的样式路由表 (LUT)，支持软件剔除（黑名单）。
* **`features_factory.csv`** — 原厂样式表的原始转储。
* **`make_exe.cmd`** — 使用 PyInstaller 将项目编译成 Windows 独立 `.exe` 的批处理脚本。
* **`dtg1_map_specification.md`** — 技术格式规范。包含 `.mlp`、`.idx` 和 `.db` 文件的逐字节结构。
## ⛰️ 等高线（实验性社区工具）
感谢 XDA-Developers 社区的贡献，本仓库现在包含用于处理地形等高线的实验性实用工具（位于 `/contours` 目录中）。这些脚本允许你在编译之前，将高程 LineString 合并到你基础的 OpenStreetMap 数据中。
如果你使用等高线功能，必须配置你的 `features.csv`。请阅读 `/contours/README_contours.md`。
## 🛠 安装和快速入门
编译器现在既支持从 Python 源代码运行，也支持编译为独立的可执行文件！
### 选项 A：独立可执行文件（仅限 Windows）
非常适合普通用户。无需安装 Python！
1. 将 `dtg1_map_compiler.exe`、`features.csv` 文件以及你的源 `map.osm` 数据放入任意方便的文件夹中。
2. 通过命令行运行可执行文件（例如 `dtg1_map_compiler.exe -p landuse`）。
### 选项 B：从源代码运行（开发者 & 跨平台）
1. 确保你安装了 Python 3.8 或更高版本。核心地图构建不需要额外的第三方依赖项（本项目完全使用内置模块）。
2. 下载仓库及其所有模块化的 Python 文件。
### 标准编译工作流
1. 从 https://www.openstreetmap.org/export 以 XML 格式导出所需的地图区域。
2. 将下载的文件重命名为 `map.osm`，并将其放在编译器旁边的工作目录中。
3. 运行脚本：`python dtg1_map_compiler.py -p landuse`
4. 编译后的二进制文件（`roads.mlp`、`roads.idx`、`landuse.db`、`map.name` 等）将出现在当前目录中。
5. 将这些生成的文件复制到手表的内部存储器中（通常通过 USB 连接放入 `MAP/Map_Name` 文件夹）。
## ⚡ 预处理大型地图（强烈推荐）
如果你正在编译大面积区域、整个国家，或者在编译过程中遇到 PC 内存溢出 (Out-Of-Memory) 错误，你应该使用 `osm_optimizer.py` 实用程序预处理原始的 `.osm` 文件。智能手表的硬件存在限制。将极其漫长的连续线条（如主要高速公路）作为单个对象渲染，可能会导致手表 UI 卡死或触发软重置 (Soft Reset)。
优化器通过以下方式解决此问题：
1. **硬件安全的分块：** 将极长的线性路线安全地切割成较小的片段（例如，每个片段 100 个顶点），同时保留闭合多边形（湖泊、森林）的数学拓扑结构，以防止扫描线渲染故障。
2. **激进的元数据剥离：** 移除沉重的 OSM 元数据（时间戳、用户、变更集）并丢弃全局黑名单标签（例如，`power`、`building`、`addr:*`），以大幅减小中间文件的大小。
## ⚙️ 命令行界面 (CLI) 参数
编译器实现了对兴趣点 (POI) 层的管理，在当前的固件版本中，该层的输出会被 ATS3085S 图形引擎在硬件层面上抑制。
可用标志：
* `-h`、`--help` — 输出可用参数的参考信息。
* `-p MODE`、`--poi-mode MODE` — 兴趣点 (POI) 数据库的生成模式。
* `none`（默认）— 在构建期间完全忽略 POI。防止数据库膨胀。
* `native` — 生成原始的 `pois.idx` 和 `pois.db` 二进制文件。可用于测试固件反应。
* `landuse` — 通过动态形状烘焙将 POI 整合到 landuse 层中。
## 🎨 样式自定义和对象过滤
`features.csv` 文件（Look-Up Table，查找表）是编译器的主要配置文件。它会在每次启动时被动态加载。
### LUT 表结构（11 列）
配置由 11 列组成，以分号 (`;`) 分隔。
**标头格式：**
```
Code;fclass;Color;LOD;Layer;OSM_Tags;Description;Remap_Code;Remap_Color;Remap_LOD;Enabled;;Shape
```
**重映射（别名）参数尤为重要：**
* **Remap_Code：** 对象将被强制转换为成的系统 32 位 ID。
* *示例：* 铺砌好的道路被映射到黄色的颜色 ID 5113。
* **Remap_LOD：** 硬件 Z-Culling 隐藏距离（以米为单位），表示缩放时对象在屏幕上显示的距离。
### 软件剔除（黑名单）
为了保护手表的图形流水线免受 RAM 溢出和 `.idx` 二进制图膨胀的影响，在流解析阶段实现了软件剔除系统。配置的第 11 列 — `Enabled` — 负责过滤。
* `1`（或 `true`）— 对象被加载到编译器中并参与地图生成。
* `0`（或 `false`）— 静音类。被硬件剔除。算法利用提前退出解析中断：遇到带有 `Enabled=0` 值的标签时，解析器会在计算 Bounding Box 之前立即丢弃该 XML 节点。这节省了 CPU 时间，并防止了被排除的对象被替换为默认的灰色或绿色样式。
### 恢复出厂设置
通过逆向工程构建的原始样式表保存在参考文件 `features_factory.csv` 中。要将所有用户对颜色、黑名单和级别细节的修改恢复为默认值：
1. 删除当前已修改的工作文件 `features.csv`。
2. 复制一份 `features_factory.csv` 文件并将其重命名为 `features.csv`。
3. 运行构建脚本，使用出厂参数值重新编译二进制文件。
## 🗺️ 自定义路线注入 (GPX)
编译器支持在基础地图上直接注入导航轨迹。
1. 将你的路线文件 (`*.gpx`) 放入 `routes/` 目录。
2. 运行构建。脚本会自动找到轨迹并提取其名称。提取出的字符串被编译到 `roads.db` 属性数据库中，确保轨迹在手表上保留其原始名称。
3. 注入的 GPX 轨迹将被转换为特定类型 `5111`（高速公路/Motorway）的对象。此代码在手表固件中是为渲染粗体、高对比度的橙色线条而硬件保留的。为了防止计划路线与实际的高速公路混淆，源 OSM 文件中的所有高速公路对象都会通过 `features.csv` 中的代码替换，强制降级为黄色类型 `5112`（干道/Trunk）。
*注意：要禁用注入并构建干净的地图，只需在启动前删除 GPX 文件即可。*
## 🔬 逆向工程工具 (`/tools`)
本仓库包含了在对 ATS3085S 图形流水线进行逆向工程期间使用的内部脚本：
* `dtg1_idx_dumper.py` — 一个反编译器，将 `.idx` 空间索引提取为可读的 CSV 格式以进行二进制分析。
* `roads_fuzzer.py` — 生成几何基元的坐标网格，以测试硬件 Z-Index 渲染和 C-Union 结构限制。
## 🔮 路线图与未来计划 (v4.1+)
核心编译引擎现已稳定。我们的下一个主要目标是将这个 CLI 工具转化为面向智能手表社区的、用户友好的“地图即服务 (Map-as-a-Service)”平台。
* [ ] **预编译的地图包：** 定期更新、可直接下载的整个国家或热门旅游地区的地图包。这些将直接托管在 GitHub Releases 中 — 最终用户无需安装 Python。
* [ ] **基于 Web 的 GUI 生成：** 一个基于浏览器的界面，用户可以在其中选择自定义的 Bounding Box（最大 50x50 公里），切换特定的图层/POI，上传他们的 GPX 轨迹进行注入，并通过连接到 Overpass API 的后端按需编译地图。标签：Python, WearPro, Zephyr, 云资产清单, 地图编译器, 无后门, 智能手表, 漏洞挖掘, 离线地图, 逆向工具, 逆向工程