## 项目概述

GeoLibre 是一个免费、开源的轻量级云原生 GIS 平台，用于可视化、探索和分析地理空间数据。它可以在 Web 浏览器、桌面端、移动端以及 Jupyter Notebook 中运行，同时保持数据本地化和隐私性。项目基于 Tauri v2、React、TypeScript、MapLibre GL JS、DuckDB-WASM Spatial 和 deck.gl 构建，并内置了 1000+ 个地理处理工具，这些工具完全在浏览器中通过 WebAssembly 运行，无需服务器或安装。

## 核心功能

- **跨平台支持**：同一代码库可构建为桌面应用（Windows、macOS、Linux）、原生 Android 应用、Web 应用，并可作为 Jupyter 小部件嵌入。
- **数据处理**：支持多种本地和远程数据格式，包括 GeoJSON、GeoParquet、Shapefile、KML/KMZ、COG、GeoTIFF、PMTiles、Zarr、LiDAR、3D Tiles 等。
- **地理处理工具箱**：内置 1000+ 个地理处理工具，涵盖矢量、栅格、遥感、水文、地形、LiDAR、转换、网络和投影等类别，全部在浏览器中通过 WebAssembly 运行。
- **SQL 工作区**：支持 DuckDB Spatial SQL、PGlite/PostGIS 和 Apache Sedona 引擎，可在浏览器中直接查询本地和远程数据。
- **样式与标注**：提供丰富的图层样式选项，包括分类、渐变、表达式、规则驱动、热力图和聚类渲染器，以及数据驱动的标注引擎。
- **插件系统**：支持内置插件和外部插件，可通过 zip、目录或托管清单 URL 安装，并提供了插件市场。
- **协作与分享**：支持实时多用户协作（MVP）、项目分享、嵌入和独立 HTML 导出。
- **AI 与自动化**：内置自然语言 AI 助手、Python 控制台、Jupyter 笔记本面板，以及 Python 和 R 包。

## 适用与不适用场景

**适用场景**：

- 需要在浏览器中快速查看和分析地理空间数据，无需安装复杂软件。
- 数据隐私要求高，希望数据保留在本地设备上。
- 使用云原生数据格式（如 COG、GeoParquet、PMTiles、Zarr、STAC）。
- 需要在桌面、Android、Jupyter 等多种环境中使用同一 GIS 应用。
- 希望将地图工作区嵌入到自己的产品中，并需要开放、文档化的项目格式和许可证。

**不适用场景**：

- 处理非常大的本地数据集（浏览器内存和 WASM 限制）。
- 需要最广泛的格式支持（GDAL/OGR 读取更多格式）。
- 需要深度专业工具箱（如 ArcGIS Pro 的 Spatial Analyst、Geostatistical Analyst 等）。
- 需要企业级数据管理（版本化编辑、复制、企业地理数据库管理）。
- 需要成熟的插件生态（如 QGIS 的数千个 Python 插件）。

## 技术架构与依赖

GeoLibre 是一个 npm workspaces 单仓库，主要包包括：

- `@geolibre/core`：领域类型、项目 JSON 模式、全局状态存储。
- `@geolibre/map`：MapLibre 生命周期、图层同步、GeoJSON、栅格、瓦片、MBTiles 等。
- `@geolibre/ui`：共享 UI 原语（shadcn 风格）。
- `@geolibre/processing`：客户端算法注册表。
- `@geolibre/plugins`：插件接口和内置插件。
- `@geolibre/embed`：用于 iframe 嵌入 API 的类型化、无依赖客户端。
- `geolibre-desktop`：外壳布局、Tauri I/O、组合。

主要依赖包括：MapLibre GL JS、deck.gl、DuckDB-WASM Spatial、Turf.js、Tauri、React、TypeScript、Zustand、Radix UI、Tailwind CSS 等。可选依赖包括 FastAPI 侧车（用于转换、栅格和 AI 分割）、Pyodide（浏览器内 Python）、CesiumJS（3D 地球视图）等。

## 安装与快速开始

### Web 端

直接访问 [GeoLibre Web](https://web.geolibre.app/) 即可使用，无需安装。

### 桌面端

从 [下载页面](https://geolibre.app/downloads/) 下载对应平台的安装包，或使用包管理器安装：

- Windows: `winget install OpenGeos.GeoLibre` 或 Microsoft Store
- macOS: `brew install --cask geolibre` 或 Mac App Store
- Linux: AUR (`geolibre-bin`)、COPR、Flatpak 或 .deb/.rpm 包

### Python 包

```bash
pip install geolibre
```

或通过 conda-forge：

```bash
conda install -c conda-forge geolibre
```

### R 包

```r
install.packages("pak")
pak::pak("opengeos/geolibre-r")
```

### 从源码运行

```bash
git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install
npm run dev  # 浏览器开发服务器，访问 http://localhost:5173
```

## 典型使用方法

### 在浏览器中加载数据

1. 打开 GeoLibre Web。
2. 通过“添加数据”菜单或拖放方式加载本地或远程数据。
3. 使用图层面板调整样式、透明度、顺序等。
4. 使用处理菜单运行地理处理工具。
5. 保存项目为 `.geolibre.json` 文件或分享。

### 在 Jupyter 中使用

```python
import geolibre
m = geolibre.Map()
m.add_geojson("path/to/file.geojson", name="My Layer")
m.fly_to(-122.4, 37.8, zoom=11)
```

### 嵌入到网页中

使用 iframe 嵌入，并可通过 URL 参数控制界面，例如 `?maponly` 隐藏所有面板，`?layout=viewer` 只读模式。

## 配置与部署要点

### 环境变量

- `VITE_GOOGLE_MAPS_API_KEY`：用于 Google Street View、3D Tiles 和交通图层。
- `VITE_MAPILLARY_ACCESS_TOKEN`：用于 Mapillary 街景。
- `VITE_PROTOMAPS_API_KEY`：用于 Protomaps 底图。
- `CESIUM_TOKEN`：用于 Cesium 3D 地球视图。
- `VITE_PYODIDE_INDEX_URL`：用于自托管 Pyodide 运行时。
- `VITE_DUCKDB_SPATIAL_EXTENSION_PATH`：用于自托管 DuckDB Spatial 扩展。

### Docker 部署

```bash
docker pull ghcr.io/opengeos/geolibre:latest
docker run --rm -p 8080:80 ghcr.io/opengeos/geolibre:latest
```

可通过环境变量配置认证、AI 代理、协作服务器等。

### 自托管分享和协作

设置 `GEOLIBRE_SHARE_URL` 和 `GEOLIBRE_COLLAB_URL` 指向自己的服务器，或使用 `docker compose` 启动参考实现。

## 限制、风险与许可证

- **许可证**：MIT 许可证，完全开源。
- **限制**：浏览器内存和 WASM 限制可能影响大型数据集的处理；部分格式（如 File Geodatabase）仅在桌面版支持；移动端隐藏了依赖本地进程的工具。
- **风险**：外部插件是受信任代码，安装前需确认来源；AI 助手会将提示和图层元数据发送给第三方提供商；协作功能会将项目数据路由到中继服务器。

## 官方链接

- GitHub 仓库：https://github.com/opengeos/GeoLibre
- 官方文档：https://geolibre.app
- Web 应用：https://web.geolibre.app
- 下载页面：https://geolibre.app/downloads/
- Python 包：https://pypi.org/project/geolibre/
- R 包：https://r.geolibre.app/

## 信息来源和分析时间

本指南基于 GitHub 仓库 [opengeos/GeoLibre](https://github.com/opengeos/GeoLibre) 的 README、文档和最新发布信息（v2.5.0，2026-08-06）编写。分析时间：2026-08-06。