android_osmdroid · Android 开源地图引擎实战工程

一套把 osmdroid 与 MapLibre 两款 Android 开源地图引擎的接入、底图、坐标、离线、图层、性能讲透的实战工程。以「技术文章 + 可运行 Demo」双轨形式，覆盖从环境搭建到工程级性能优化、踩坑实录的完整链路。

工程包含同一套地图能力的两个对照实现：基于 osmdroid（命令式 Canvas 绘制）与基于 MapLibre（GPU 声明式图层），便于在不同项目诉求下选型与迁移。

---

一、工程概览

项	内容
工程类型	Android Gradle 多模块工程（根 Project + 2 个 Application 模块）
构建工具	AGP 7.1.2 + Kotlin 1.6.10，Gradle 7.x（含 gradlew / gradlew.bat）
统一配置	config.gradle 注入 compileSdk=31 / minSdk=23 / targetSdk=28 / kotlin=1.6.0
仓库	阿里云镜像 + jitpack + google + jcenter
语言	Kotlin，约定最小可运行、兼顾可读性
配套文档	docs_articles/ 共 21 篇技术文章（osmdroid 14 篇 + MapLibre 7 篇）

---

二、模块结构

android_osmdroid/
├── settings.gradle              # 包含 :osmdroid_demo 与 :maplibre_demo 两个模块
├── build.gradle                 # 顶层构建（config.gradle 注入、仓库、插件）
├── config.gradle                # 统一 SDK / Kotlin 版本
├── maplibre_demo/               # 模块一：MapLibre Android SDK 实战（15 篇演示页）
│   ├── README.md                # 模块说明
│   ├── src/main/                # MainActivity + common/ + article01~15
│   └── pic/ articles/           # 截图与配套文章占位
├── osmdroid_demo/               # 模块二：osmdroid 6.1.11 实战（12 篇演示页）
│   ├── README.md                # 模块说明
│   ├── src/main/                # MainActivity + common/ + article01~12
│   ├── proguard-project.txt     # 混淆配置
│   └── pic/                     # 运行截图
└── docs_articles/               # 配套技术文章（21 篇 .md）
    ├── 0x_osmdroid_*.md         # osmdroid 系列 14 篇
    ├── maplibre_*.md            # MapLibre 系列 7 篇
    └── osmdroid_README.md / maplibre_README.md  # 两个系列导读

两个模块对照

维度	osmdroid_demo	maplibre_demo
引擎	osmdroid 6.1.11	MapLibre 10.2.0（11.x 需 compileSdk 34，不兼容当前 AGP 故回退）
渲染范式	命令式 Canvas 逐要素绘制	GPU 声明式 Source + Layer 模型
演示页	12 篇（article01~12）	15 篇（article01~15）
应用 ID	com.example.osmdroiddemo	com.example.maplibredemo
公共层	common/（BaseMapActivity / BaseMapView）	common/（BaseMapActivity / 瓦片工厂 / 纠偏 / 图层模型等）

两个模块的结构高度同构：首页 MainActivity 以 RecyclerView 列出篇章目录，点击进入对应演示 Activity，实现「读文章 → 跑 Demo 验证」的闭环。

---

三、配套技术文章（docs_articles/）

工程的核心资产之一，共 21 篇，每篇均可独立阅读，文末「延伸阅读」串联前后篇形成闭环。

osmdroid 系列（14 篇）

入门与环境搭建、视图封装与生命周期、在线瓦片源·谷歌、在线瓦片源·天地图、离线地图加载方案、坐标纠偏原理与实战、图层系统设计与持久化、矢量数据绘制与坐标变换、屏幕/测量坐标互转、Overlay 体系与自定义绘制、手势交互与罗盘方向、工程踩坑与性能优化实录、数万点绘制性能优化、极值缩放边界策略。

MapLibre 系列（7 篇）

坐标系纠偏原理与转两次陷阱、自定义比例尺屏幕距离换算、海量点三级过滤渲染管线、离线地图三路线、瓦片源工厂多域名与压级别、范围缩放由分辨率反推缩放级别、统一图层模型与 XML 持久化。

两系列关系

• 同源不同实现：通用原理（GCJ-02 纠偏数学、三级过滤、地面分辨率、离线三路线、统一图层模型）两系列完全一致。
• 差异仅在引擎专属实现：MapLibre 的 TileSet 模板数组、密封类图层模型、GPU 圆点图层、声明式 Symbol/Line/Fill 等。
• 每篇 MapLibre 文章末尾回指对应的 osmdroid 篇，形成跨引擎对照闭环。

---

四、通用核心原理（两系列共享）

工程沉淀了一套与具体引擎无关的地图方法论：

• 瓦片金字塔 / Web Mercator：在线瓦片投影与分级组织方式。
• 坐标纠偏：WGS-84 ↔ GCJ-02（火星坐标）双向换算；平面测量坐标系下「转两次」的转换链。
• 三级过滤海量点：范围裁剪 → 像素叠加 → 几何分析，再交给 GPU/Canvas 渲染屏幕量级要素。
• 离线三路线：矢量现算 / 影像贴图（地理四角）/ 瓦片归档。
• 地面分辨率驱动：自定义比例尺、范围缩放（由分辨率反推 zoom）均由 C·cos(lat)/(256·2^z) 公式驱动。
• 统一图层模型：配置模型 + 渲染管线路由 + XML 持久化，屏蔽多数据类型差异。

---

五、权限与配置

两个模块均声明：

• INTERNET / ACCESS_NETWORK_STATE / ACCESS_WIFI_STATE：在线瓦片源必需；
• ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION：罗盘方向（传感器）演示必需；
• android:usesCleartextTraffic="true"：允许明文 HTTP 瓦片调试。

---

六、构建与运行

# 用 Android Studio 打开根工程 android_osmdroid
# 构建 osmdroid 模块
./gradlew :osmdroid_demo:assembleDebug

# 构建 MapLibre 模块
./gradlew :maplibre_demo:assembleDebug

运行要求：

• Android SDK Platform 31 + 对应 Build-Tools；
• 设备/模拟器系统版本 ≥ Android 6.0（API 23）；
• 在线底图演示需联网；离线相关演示可脱离网络。

---

七、快速导航

• 想看 osmdroid 实现 → 打开 osmdroid_demo/，对应文章见 docs_articles/0x_osmdroid_*.md
• 想看 MapLibre 实现 → 打开 maplibre_demo/，对应文章见 docs_articles/maplibre_*.md
• 想先读系列导读 → docs_articles/osmdroid_README.md 与 docs_articles/maplibre_README.md
• 模块级说明 → osmdroid_demo/README.md、maplibre_demo/README.md

---

八、设计思想小结

1. 读验一体：技术文章与可运行 Demo 绑定，避免「只看不动」。
2. 收口复用：地图初始化、生命周期、视野同步等易错点集中在 common/，各演示页只聚焦差异化业务。
3. 双引擎对照：同一能力用命令式与声明式两种范式实现，便于选型、迁移与原理对照。
4. 工程导向：集中沉淀生产环境真实踩坑（压级别防崩溃、长路径分段、降采样、范围缩放），而非停留在 API 调用层面。

---

九、项目动态与交流

项目更新、配套教程同步发布在公众号：测码翁

[扫码关注：测码翁]