# mapdoc

**Repository Path**: araxit/mapdoc

## Basic Information

- **Project Name**: mapdoc
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MapDoc — 地图文档（原生 Android，完全离线）

把地图当作**可编辑文档**的原生 Android App：SQLite 结构化地图数据、MapLibre 2D 地图、
自研 Filament 3D 地球（契约已就绪）、指定区域导出 `.mdd` 地图文档包并可再导入。

## 行走记录与区域化展示（完全离线）
- 「开始记录」后用系统 GPS 逐点采样，每点保存**极坐标**（相对上一点的方位角 θ + 距离 r）、经纬度与海拔
- 行走模式随时切换（**类型位掩码**）：`0`=随便走走、`1`=田地、`2`=路、`4`=建筑，`8/16/32/64` 预留；模式可叠加（xor 切换）
- **三角形渐变展示**：不逐点渲染。所有 GPS 点实时做 **Delaunay 三角剖分**（JTS），
  数学上保证三角面**互不重叠**；每个顶点按类型着色（灰=随便走走 绿=田地 黄=路 棕=建筑），
  三角面颜色 = 三顶点混合色，形成渐变马赛克效果；跨越空隙的超长边（>120m）自动丢弃；
  三角面仅在内存中实时生成、**不落数据库**，每次新增点自动重算
- 手动加点/画线/画面能力保留
- 底图仅读本地 tiles.db（MBTiles 格式），无任何在线请求

## 技术栈
- Kotlin 2.0 + Jetpack Compose（Material3）
- 2D 地图：MapLibre Android（栅格瓦片 + GeoJSON 要素）
- 3D 地球：Filament（`map-render/globe/GlobeRenderer` 契约，阶段 3 接入实现）
- 数据：Room（documents/layers/features/tile_sources）+ 原生 SQLite 瓦片库（MBTiles 兼容，TMS y）
- 导出格式：`.mdd` = ZIP{ manifest.json + tiles.sqlite + features.json }，带 sha256 校验与合并策略

## 模块结构
```
app/            Compose UI：文档列表、编辑器（加点/画线/画面/图层）、导出向导
map-document/   纯 Kotlin 领域层：MapDocument/Feature/GeoBounds、TileMath、TileClipper、
                MddExporter/MddImporter、MergeStrategy（含 TileFileReaderProvider SPI）
map-data/       Room AppDatabase、TileDbHelper（tiles.db, WAL）、TileRepository、
                TileDownloader（区域预下载）、DocumentRepository
map-render/     MapViewport（2D/3D 共享状态）、MapLibre2D 封装、GlobeRenderer 契约
```

## 构建运行
需要 Android SDK 34 + JDK 17：

```bash
cd MapDoc
gradle wrapper --gradle-version 8.9   # 或直接在 Android Studio 中打开
./gradlew :app:assembleDebug
```

产物：`app/build/outputs/apk/debug/app-debug.apk`

## 已实现（阶段 1+2）
- 新建/打开/删除地图文档；OSM 在线底图 + 本地瓦片缓存（tiles.db）
- 地图点击加点、多点连线/画面，要素落 SQLite 重启不丢
- 图层显隐开关
- 导出：设定 zoom 范围 → 范围内瓦片 + 相交要素打包为 `.mdd`（含 sha256）
- 导入：从 Download 目录读取 `.mdd`（SKIP/REPLACE/NEW_DOCUMENT 三种合并策略）
- 区域预下载（`TileDownloader.prefetch`）支持完全离线浏览

## 待办（阶段 3/4）
- Filament GlobeRenderer 实体实现（球体网格、瓦片四叉树 LOD、轨道相机、屏幕空间要素）
  契约与 2D/3D 切换对齐逻辑见 `map-render/src/main/kotlin/com/example/mapdoc/render/globe/GlobeRenderer.kt`
- 地图框选范围手势（MVP 导出直接用文档 bounds）
- SAF 文件选择器替换 Download 目录导入；FileProvider 分享 .mdd