Atlas Compass

A fully offline geographic knowledge system for Obsidian. Bring your own GPS history (CSV / GPX exports from any tracking app) and Atlas Compass turns it into an interactive, completely offline world map with travel statistics — no network access required, ever.

Features

• Offline vector map — country, province, and city boundaries (world, China, Japan) rendered with Leaflet; nothing is fetched from tile servers
• GPS track import — CSV / GPX with automatic trip segmentation and transport classification (walk / bike / car / coach / high-speed rail / metro / train / plane), plus teleport, spike, and U-turn cleaning
• Stay detection — adjacency-cluster stay points with a hybrid validity rule (time span, displacement, and accuracy quality), mirroring what commercial trackers do
• Visit determination — three strictness levels based on cumulative dwell time or single-stay length; home-city visits can be simplified to monthly entries
• Lit map — visited countries, provinces, and cities light up in warm gold; click a lit region for visit statistics
• Land coverage grid — 494,312 geohash cells across China's land area, lit by your tracks, with a coverage percentage and a printable SVG report
• Trip notes — auto-generated multi-day trip reports with emoji transport icons, wikilinked city notes, daily distances, and altitude profile SVGs
• Year in review — per-year rankings, monthly distribution bars, and newly visited cities
• Photo footprint — scans JPG EXIF in your vault (config folder excluded) and builds a photo-travel report
• 34,149-city geocoding fallback (GeoNames) — worldwide city attribution for tracks outside covered admin2 datasets
• 131 airports with Chinese names for flight detection

Manual installation

1. Download main.js, manifest.json, styles.css from the latest release into <vault>/.obsidian/plugins/atlas-compass/, then enable the plugin.

2. Data folder (optional). Everything needed for daily use is embedded in the bundle: country, province, and city boundaries (China & Japan), the 34,149-city library, and the coverage grid — the map is fully functional straight from the release. The repository's data/ folder (about 75 MB) only adds high-detail boundary rendering when zoomed in past z7 (LOD hot-swap). To install it:

   git clone --depth 1 https://github.com/Loulan23253/atlas-compass.git
   cp -R atlas-compass/data <vault>/.obsidian/plugins/atlas-compass/
   

   Then restart Obsidian.

Usage

1. Run 打开 Atlas 旅行地图 (Open Atlas travel map) from the command palette.
2. Create city notes (type: city frontmatter) manually or import from CSV/JSON.
3. Drop GPS CSV / GPX files into the import dialog (ribbon or command palette) — tracks, stays, transport modes, and coverage are derived automatically into Travel/.

Privacy & network

Atlas Compass performs zero network requests. All boundaries, the city library, and the coverage grid ship inside the plugin's data/ folder. The only optional network feature is geocoding for the manual "add city" flow, which you can disable by leaving the endpoint setting on Photon or replacing it — no track, location, or vault data ever leaves your device.

Documentation

完整的中文文档见下方（The rest of this README is in Chinese）.

---

Atlas - 旅行地图插件

一个功能强大的 Obsidian 旅行地图插件，支持完全离线的世界地图和中国、日本的市级行政区划。

✨ 主要特性

🗺️ 离线世界地图

• 国家级：全球 200+ 国家边界（Natural Earth）
• 省级：全球省/州级行政区划（39MB）
• 市级：中国 370+ 地级市（3.2MB）、日本 1800+ 市町村（2.6MB）
• 自动切换：根据缩放级别自动显示对应层级

📍 旅行记录

• 城市/地点标记
• 访问次数统计
• 最近访问日期
• 自动生成坐标质心

🧭 路线与洞察

• 点亮地图：去过的国家/省份/城市在地图上暖金色点亮（有到访记录即点亮），点击点亮区域查看到访统计
• 旅行路线连线：按日期串联到访城市，按年份配色，点击线段查看两地距离，地图角标显示总里程
• 探索覆盖率：中国城市、日本都道府县的到访进度条
• 常用机场：内置 130+ 常用机场（中国干线与热门旅游、日本主要、国际枢纽，坐标取自 OurAirports）（✈ 按钮开关），点击查看详情与离家距离，可一键建档为地点
• 日记驱动建档：日记里 [[提到]] 但未建档的城市，一键创建并自动定位

📥 批量导入

• 命令面板 →「导入城市（CSV / TSV / JSON）」，可直接从电脑选文件，无需先拷进仓库
• CSV 首行列名支持中文：名称/城市、国家、纬度、经度、访问次数、访问日期（多个用 | 分隔）、最近访问、备注、类型（city/place）
• 自动识别逗号/分号/Tab 分隔符，支持带引号的跨行单元格；导入前预览，已有城市可选「补充坐标」
• GPS 轨迹导入：自动识别运动健康类 App 的打点导出（时间戳+经纬度列）——按天抽稀后保存为 Travel/轨迹/日期.geojson 并在地图上显示（GPS 按钮开关）；可选「自动记录到访城市」，按天驻留分析判定到访城市（中国、日本等已配置市级数据的国家）写入城市笔记：「常用地点」（设置里指定）按月简化，其他城市记完整日期，未建档的自动创建
• 行程识别：导入时按天切分路径（间隔 ≥1801s 断段、≥3 点、≥20m）并识别交通方式（步行/骑行/驾车/高铁/火车/地铁），路径数与方式分布显示在导入预览、写入轨迹文件属性（trips/transport）；行程内驻留按 150m 邻接聚簇、簇时长 ≥10 分钟识别；「到访判定」（设置里）分三档：宽松 = 当天打点即可，标准 = 当天在该市累计 ≥2h 或单段连续 ≥30min，严格 = 当天累计 ≥6h；CSV 里的 accuracy/speed/altitude 列直接参与识别
• 全球城市兜底：内置 34,149 城离线城市库（GeoNames，CC-BY 4.0；geohash 同格最近城匹配）——admin2 市级多边形未覆盖的国家，GPS 到访照样落城市
• 性能：点面匹配使用 0.5° 网格空间索引（较线性扫描 ~8x）；地图边界按缩放级别加载 LOD 简化版（启动只解析简化边界，高缩放懒加载全精度热切换）；矢量层 canvas 渲染
• 轨迹清洗：导入时自动剔除瞬移点（隐含速度 >300km/h）、三角/四角 GPS 折返尖峰、急转折返（转角 >135° 且有实际移动），Z 形漂移校正 + 近共线点平滑；剔除点的时间戳持久化到轨迹属性（ignoredTs）可审计
• 行程方式修正：命令面板 →「修正行程交通方式」选日期，逐段下拉改方式（保存后 segments/transport 属性同步更新）
• 导入历史：命令面板 →「查看导入历史」——每次导入的文件、哈希、天数、点数、清洗数
• 道格拉斯-普克抽稀：轨迹按形状保留关键点（阈值 10m），同样的点数画出更真实的线
• 长间隔插值：≥10 分钟且 ≥1km 的断口自动补插值点，地图上以虚线弱化显示（飞机/高铁关 GPS 的推断航段）
• 国土覆盖率：导入时点亮中国陆地 5 位 geohash 格（约 4.9km 见方，共 494,312 格）；命令面板 →「生成国土覆盖率报告」输出 Travel/国土覆盖率.md；地图左上角「格」按钮可在地图上直接画出点亮的格点（半透明矩形）
• 年度回顾：命令面板 →「生成年度回顾」生成 Travel/年度回顾/年份.md——到访城市数、新增城市、到访排行、月度分布
• 旅程笔记：命令面板 →「生成旅程笔记」——把连续活动日（间隔 ≤2 天）聚合成一次旅程，生成 Travel/旅程/ 笔记（frontmatter 含 start/end/cities/km，正文逐日表格）
• 照片点亮足迹：命令面板 →「照片点亮足迹」——扫描库内 JPEG 的 EXIF GPS 与拍摄时间，点亮城市/格点并合并到访日期，报告写入 Travel/照片足迹.md
• GPX 导入：.gpx 文件走与 CSV 相同的清洗/识别管线（多 trkseg、海拔）
• 方式分色：轨迹按段按交通方式上色（步行绿/骑行蓝/驾车橙/高铁红/火车深红/地铁紫），地图一眼看清当天怎么走的
• 增量导入：重复导入时自动识别已导入的部分——预览里标记每天是「新」还是「已导入」，内容未变化的天直接跳过，只有新增天数和有变化的天会写入；到访日期已记录的自动跳过

🎯 自动定位

• 通过 Geocoding 服务按「城市名, 国家」自动查坐标（默认 Photon 免 key，可换 Nominatim）

📦 数据文件结构

atlas_v3/
├── data/
│   ├── countries.geojson        # 国家边界 (819KB)
│   ├── admin1.geojson           # 世界省级边界 (39MB)
│   ├── admin1.lo.geojson        # 省级 LOD 简化版 (18MB，启动加载)
│   ├── worldcities.json         # 全球城市兜底库 34,149 城 (3.3MB)
│   ├── chinacells.txt           # 中国国土覆盖率 geohash 格点 (2.4MB)
│   └── admin2/
│       ├── china_admin1.geojson # 中国省级 (569KB)
│       ├── china_admin2.geojson # 中国地级市 (3.2MB)
│       ├── china_admin2.lo.geojson # 中国地级市 LOD 简化版 (2.6MB)
│       ├── jpn_admin2.geojson   # 日本市町村 (2.6MB)
│       └── jpn_admin2.lo.geojson   # 日本市町村 LOD 简化版 (1.4MB)
└── src/
    └── map/
        ├── GeoJsonLoader.ts     # 多级数据加载器
        └── MapView.ts           # 地图渲染引擎

其中 .lo.geojson 简化边界由 npm run lod 重生成（道格拉斯-普克逐环简化，脚本为 scripts/generate-lod.mjs）；chinacells.txt 由 npm run cells 重生成（Natural Earth 中国边界栅格化，脚本为 scripts/generate-cells.mjs）。其余为来源数据，更新后可直接运行对应脚本重算派生产物。

🚀 安装

1. 下载插件到 .obsidian/plugins/atlas_v3/
2. 运行 npm install
3. 运行 npm run build
4. 在 Obsidian 中启用插件

🗺️ 地图使用

视图切换

• 自动：根据缩放级别自动切换
• 国家级：缩放级别 ≤ 4
• 省级：缩放级别 5-7
• 市级：缩放级别 ≥ 8

交互操作

• 鼠标悬停：高亮区域
• 鼠标点击：选中区域并显示详情
• 滚轮缩放：切换显示层级
• ⌖ 按钮：重置视图到全球范围

数据加载

• 中国、日本的市级数据已内置，进入市级缩放级别时同时显示
• 点击其他国家会尝试加载该国的市级数据文件（如 fra_admin2.geojson），没有则提示

📝 旅行笔记格式

在笔记的 frontmatter 中添加：

---
type: city  # 或 place
name: 城市名称
country: 国家
lat: 39.9042
lng: 116.4074
visits: 3
lastVisit: 2024-01-15
---

🔧 设置选项

选项	说明
旅行笔记根目录	扫描此目录下的笔记
日记链接扫描	已改为全库扫描：任何目录下形如 2026-08-07.md 的日记都参与 [[城市]] 链接统计与到访派生，无需配置
默认地图中心	地图初始中心点（可用「采用当前视野」一键取自地图）
默认缩放	地图初始缩放级别
常用地点	常住地城市名（如「苏州市」）：GPS 导入时该城市按月简化记录，其他城市记完整日期；留空则全部完整日期
到访判定	GPS 轨迹怎样算「到访」：宽松 = 当天打点即可；标准 = 当天累计 ≥2h 或单段 ≥30min；严格 = 当天累计 ≥6h
地理编码服务（自动定位）	Geocoding 服务地址（默认 Photon 免 key，可换 Nominatim）

📊 数据来源

数据	来源	说明
国家边界	Natural Earth	全球 200+ 国家
省级边界	Natural Earth	全球省/州级
中国地级市	DataV GeoAtlas	阿里云数据可视化
日本市町村	GADM 4.1	全球行政区划数据库

🛠️ 开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 生产构建
npm run build

📄 许可证

MIT License

🙏 致谢

• Natural Earth - 全球地理数据
• DataV GeoAtlas - 中国行政区划数据
• GADM - 全球行政区划数据
• Leaflet - 地图库

🔐 隐私与网络

• 本插件完全离线运行：地图边界、城市库、国土格点全部内置，无任何遥测或数据上报
• 唯一的网络请求是「地理编码服务」——仅当你手动创建新城市笔记并使用自动定位时，向 Photon/Nominatim 发送城市名称（不含你的位置或轨迹数据）