Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

GeoLibre

一款免费开源、轻量、云原生的 GIS 平台，用于可视化、探索和分析地理空间数据。它可在您工作的任何地方运行——Web 浏览器、桌面、移动端以及 Jupyter notebook 中——同时让您的数据保持本地化和私密性。

GeoLibre 基于 Tauri v2、React、TypeScript、MapLibre GL JS、DuckDB-WASM Spatial 和 deck.gl 构建。同一工作区可作为原生桌面应用、原生 Android 应用运行，也可在任何现代 Web 浏览器中运行，并能响应式适配移动端和小屏幕。

视频教程：

• GeoLibre 1.0: A Free, Open-Source Cloud-Native GIS That Runs Anywhere (Browser, Desktop & Jupyter)
• Geoprocessing in the Browser: 700+ Free GIS Tools in GeoLibre, Zero Install

Features (v2.0)

• 跨桌面（Tauri）、Web（浏览器）、原生 Android（Tauri v2 mobile）以及移动端或小屏幕运行，采用响应式、触控友好的布局，可自适应菜单、对话框和面板（在手机上，图层/样式面板以滑出式 sheet 覆盖在地图之上），并可通过布局设置控制各面板的可见性
• MapLibre 地图工作区，提供 OpenFreeMap、Protomaps、EOX Sentinel-2 cloudless 和 Openbasiskaart 底图，以及火星和月球的行星底图（OpenPlanetaryMap），还有水星、金星、伽利略卫星（Io、Europa、Ganymede、Callisto）、Titan、Pluto 和 Charon（USGS Astrogeology，由 tiles Worker 重投影至 Web Mercator），每个项目配有椭球体，其半径驱动距离、面积和比例尺测量，图层面板中提供行星切换器；支持叠加多个栅格底图、空白背景、双击从图层面板切换核心底图、右键上下文菜单读取坐标并执行快捷操作、带边缘标注的 Gridlines 坐标网格叠加层及 UTM 东向/北向网格模式，并可切换导航、全屏、定位、地球仪、地形、比例尺、归属和徽标控件；视图菜单提供视口历史导航、重置俯仰角与方位角控件、独立指北针，以及“在 Google Maps 中查看”和“在 Google Earth 中查看”操作，还有双击地形控件用于设置垂直夸张
• 多地图网格将工作区拆分为同步的地图视图网格，便于并排比较底图、图层或时间步；任意窗格可切换为可选的 CesiumJS 3D 地球仪（与 2D 地图相机同步；需要 Cesium Ion token — 参见 Environment variables）
• 加载 DuckDB-WASM Spatial 支持的本地矢量图层，包括 GeoJSON、GeoParquet、GeoPackage、Shapefile、FlatGeobuf、KML/KMZ（保留嵌入符号化，将 GroundOverlay 图像渲染为地图叠加层并在带时间标签时通过时间滑块动画播放，并显示嵌入的 Collada .dae 3D 模型）、GML、分隔文本（包括无坐标 CSV，作为独立属性表加载）、GPX 和 OpenStreetMap PBF 提取文件（在浏览器内用 osmix 解析）等常见格式
• 加载时将矢量图层重投影至 EPSG:4326，渲染携带 Z 坐标的矢量图层时为真实 3D 而非压平到地面，并将拖入的 GPX 文件拆分为命名的航点、轨迹和路线图层
• 大型本地矢量图层通过客户端矢量切片渲染，加载超大文件前会显示警告
• “添加数据”菜单支持 XYZ 瓦片、WMS 和 WFS（通过服务的 GetCapabilities 发现图层和要素类型，可从填充好的下拉列表中选择）、GeoJSON URL、GeoRSS 源（URL 或文件）、矢量瓦片（包括 OGC API - Tiles 矢量瓦片服务）、COG 和 GeoTIFF 栅格、Cloud-Optimized NetCDF/HDF（通过 kerchunk 引用）以及本地 HDF5 和 NetCDF-4 文件、MBTiles、ArcGIS FeatureServer 和 VectorTileServer 图层、PMTiles、Zarr、LiDAR、3D Tiles（包括通过自定义请求头进行身份验证的瓦片集）、ArcGIS I3S 场景图层（Integrated Mesh 和 3D Object 图层在 deck.gl 上渲染）、CAD 图纸（DXF/DWG，带图纸图层选择器和 CRS 选择器）、Gaussian splats、按坐标放置的 glTF/GLB 3D 模型、地理参考视频叠加层，以及从 EXIF GPS 导入为点图层的地理标记照片（对无坐标照片支持手动放置和拖拽）；对话框完全国际化，支持逗号小数、拖放 CSV 坐标文件，每个上游数据面板均提供示例数据下拉列表以加载现成示例数据集，并提供已保存服务库用于存储和重新添加常用 Web 服务端点
• Deck.gl 图层构建器，可从上传文件或远程 URL 组合 deck.gl 叠加层
• 通过 Planetary Computer 和 Earth Engine 面板、Overture Maps 插件以及联邦 Web Services 插件实现云数据集成
• WFS、GeoJSON URL 和“添加矢量图层 URL”图层的手动与自动刷新
• 图层面板支持可见性、不透明度、重排序、重命名、缩放到图层、识别、标注、打开属性表、导出和移除操作，带可折叠图层组/文件夹以组织图层栈，页脚提供“搜索地点”框用于地理编码定位而无需离开面板
• 实时样式面板，支持单一、分类、分级、表达式和基于规则（由过滤器驱动）的符号化（填充、描边、不透明度、圆点半径）、比例符号、填充图案、内置标记库，以及点热力图和聚类渲染器——均适用于“添加矢量图层”点图层；内联色带选择器在触发器上和每个选项旁预览各色彩映射表的渐变，颜色选择器提供透明（无填充/无轮廓）选项；矢量图层符号化可导入导出为 OGC SLD、QGIS QML 和 Mapbox GL style JSON，使样式可在 GeoLibre、QGIS 与 Mapbox/MapLibre 生态之间往返
• 标注引擎可按任意属性为矢量要素添加标注，提供 ArcGIS 风格的放置与样式控件（锚点、X/Y 偏移、旋转、换行宽度、字母大小写）、“重复标注”选项，以及将堆叠在同一坐标的点合并为单一去重标注的唯一/连接模式
• 属性表支持过滤、排序、调整大小控件，要素高亮，Ctrl- 和 Shift- 点击多行选择，可选缩放到所选要素，添加字段和字段计算器工具（包括几何长度和面积计算），图表面板（直方图、散点图、柱状图、折线图、箱线图），字段统计摘要面板，列管理（重命名、删除、隐藏/显示、重排序）及列浏览器以便在宽表中查找和切换字段，大型图层采用虚拟化行，并可导出为 GeoJSON/GeoParquet/Shapefile/GeoPackage/CSV
• SQL 工作区可对已加载图层、本地文件和远程 URL 运行 DuckDB Spatial SQL，作为可调整大小的面板停靠在地图旁，编辑器为表、列和 SQL 关键字提供自动补全，含示例查询、查询历史，以及将结果添加到地图或导出；另提供浏览器内 PostGIS SQL 引擎（通过 PGlite）和 Apache Sedona 空间 SQL 引擎
• 多个 DuckDB SQL 查询结果图层，支持识别、选择和属性表
• “控件”菜单提供测量、书签、小地图、视图状态和地图标注工具（在地图上绘制文字、箭头和高亮，随项目保存），搜索面板，路线和反向地理编码工具的持久模式横幅，摄像机动画录制器可将关键帧动画录制为视频（支持逐关键帧重新捕获、逐关键帧停留与过渡时长控制，以及以 JSON 保存/加载命名游览设置），可配置图表小部件的仪表板面板用于汇总已加载图层，以及打印菜单（带打印布局编排器：用户可编辑图例、显式地图比例尺输入、带可编辑标题和页脚的文字块、页面尺寸控件、自定义打印范围，以及复制到剪贴板），可将地图导出为 PNG 或 PDF
• “天气”菜单提供实时云图和降水雷达叠加层（RainViewer），“控件”菜单中的云图叠加层，以及 Google Earth 风格的太阳位置模拟，按给定日期和时间照亮场景
• 书签在捕获相机的同时记录活动图层，按文件夹组织，支持选择性导出、可调整大小和重排序的面板，以及“另存为”名称提示
• 野外采集工具用于采集点、线和面观测，每层配有自定义表单（文本/数字/日期/选择字段及可选照片），通过设备 GPS 或点击地图放置，写入 GeoJSON 图层并流入属性表、导出和离线使用
• 故事地图构建器直接在实时地图上编排章节，提供演示者视图、专用开场与结束幻灯片、可选隐藏行程开关、可打印 PDF 讲义生成器（含副标题和署名栏），以及独立 HTML 导出
• 实时多用户协作（MVP；需要 VITE_GEOLIBRE_COLLAB_URL 构建变量 — 参见 docs/collaboration.md），多人可同时编辑同一项目，含按参与者权限、应用内聊天面板，以及会话进行中的画布上会话状态徽章和名册（实时圆点、已连接参与者数量及可展开客户端列表）
• 自然语言 GIS 助手将 plain-English 请求转化为可审计、可撤销的 GeoLibre 操作（Spatial SQL、符号化、添加/移除数据和地图控制），提供商可插拔并使用您自己的 API 密钥（也可从 OS 环境变量读取），设有专用 AI Providers 设置区及各功能提供商下拉列表
• 应用内 Python 控制台及用于脚本化应用的 Python 自动化 API
• Notebook 面板停靠在地图旁，针对实时地图运行 Jupyter：Web 构建嵌入自托管 JupyterLite 站点（浏览器内 Pyodide 内核），桌面构建启动 uv 管理的 JupyterLab 服务器，notebook 单元格通过自动加载的 geolibre 客户端驱动地图。参见 Notebook Panel
• 命令面板（Ctrl/Cmd + K），可搜索并执行“添加数据”、“处理”、“控件”、“插件”和“帮助”中的菜单与工具栏操作；全局键盘快捷键用于新建/打开/保存/另存为及 Google Earth 风格相机重置（N 指北朝上、U 俯视、R 重置视图），以及 ? 快捷键速查表
• “转换”菜单支持矢量转 GeoParquet/FlatGeobuf/PMTiles、按文件扩展名在任意支持矢量格式间转换的通用矢量转矢量转换器、CSV 转 GeoParquet 以及栅格转 COG；GeoParquet 和 CSV 转换在浏览器内通过 DuckDB-WASM 运行，FlatGeobuf、PMTiles 和 COG 需要可选 Python sidecar
• Whitebox 工具箱完全在浏览器内通过 WebAssembly 运行时运行，支持栅格 I/O（无需 Python sidecar），同时提供 Whitebox 工具和 GeoLibre 自有 WASM 栅格工具，可在“处理”菜单中按类别浏览，含嵌套子类别子菜单和离线捆绑工具目录，支持对所选输入目录批量运行工具
• “矢量”菜单提供常见几何与分析工具（缓冲区、质心、凸包、融合、边界框、简化、裁剪、相交、差集、联合、空间连接、属性连接、按值选择、按位置选择、移动、时空和单元覆盖），在浏览器内通过 Turf.js 运行，每个工具可选 GeoPandas sidecar 引擎，以及通过 Pyodide 的浏览器内 GeoPandas 引擎（无服务器，结果与 sidecar 相同）
• “栅格”菜单提供常见栅格工具（山体阴影、坡度、坡向、重投影、重采样、按范围裁剪、按掩膜图层裁剪、栅格化、等高线、分区统计、栅格计算器、重分类、镶嵌、焦点统计），由 rasterio Python sidecar 支持，并提供客户端回退，使核心工具在无 sidecar 时也可在浏览器内运行；另支持在浏览器内提取 COG、WMS 和 XYZ 边界框子集，以及为任意 HTTP COG 构建归一化差异指数
• 光谱指数工具箱（NDVI、GNDVI、NDWI、NDMI、NDBI、NBR、EVI、SAVI），支持 Sentinel-2、Landsat 8-9、NAIP 和自定义波段布局，在客户端通过 geotiff.js 评估或在 rasterio sidecar 上评估
• 空间统计工具箱及处理批处理运行器，支持模型/流水线链式调用，将一系列工具作为单一作业运行
• 栅格地理配准器（处理 → 地理配准）通过地面控制点将未地理参考图像钉合到地图，采用最小二乘仿射拟合，报告各 GCP 和 RMS 残差
• 单波段伪彩色，支持分类、反转和自定义色带，完整色彩映射表列表在色带选择器中以内联渐变色块显示，调色栅格的嵌入颜色表自动填充图例，以及 RGB 波段组合用于栅格图层样式；另支持通过识别图标检查 COG 像素值
• 网络分析工具，通过有序航点集提供等时线、服务区域、起讫点（OD）成本矩阵和顺序路线（路线规划）
• 地理编码工具，通过多提供商抽象支持正向、批量和反向地理编码
• AI 分割（SamGeo）将影像转化为矢量要素，使用 segment-geospatial 和 Meta 的 SAM 3 — 文本提示（"trees"、"buildings"）或自动分割，代理至独立的 samgeo-api 模型服务器（建议使用 GPU）
• H3 工具可在范围内创建六边形网格，并将点图层分箱到 H3 单元
• 图层和样式操作的撤销/重做
• 将矢量和 GeoTIFF/COG 栅格文件拖放到地图上以添加为图层
• “项目”菜单用于创建、打开、保存和另存为 .geolibre.json 项目，将项目导出为无需服务器即可离线运行的单一独立交互式 HTML 文件，以及项目库用于一键浏览和打开共享项目
• 桌面诊断面板（在网络日志中捕获原生 Tauri HTTP 请求并分类失败的 fetch() 错误）、带启动更新检查和更新偏好的引导式更新工作流，以及 MSIX 打包支持；macOS 安装包使用 Apple Developer ID 证书签名并经 Apple 公证，无需 Gatekeeper 变通即可打开；另提供 Windows Package Manager（winget）分发为 OpenGeos.GeoLibre，以及无需安装的 Windows 便携 zip 构建
• 可自定义 UI 配置文件，定制可见的菜单、面板和数据源，使部署可向用户呈现应用的聚焦子集。参见 UI Profiles
• 插件系统，集成底图、图层控制、MapLibre 组件、卷帘、街景、Mapillary 覆盖与街景图像查看器、历史影像、高程剖面、Overture Maps、USGS LiDAR、GeoAgent 和 GeoEditor（GeoEditor 可将当前地图视图中可见的矢量要素拉入编辑器进行编辑而无需重新导入源，并将编辑写回其来源，包括 GeoPackage 和 GeoJSON 文件以及 PostGIS 数据库表），包括可配置控件位置和外部插件清单；外部插件可通过 app.getDeckGL() 在宿主共享 deck.gl 实例上渲染，使用 maplibre-gl-raster 栈和地图投影控件，注册原生栅格和瓦片图层，通过插件 UI 宿主 API 注册一级右侧边栏面板、工具栏菜单和浮动面板（包括共享导轨替换式停靠模式），并将其工具栏菜单置于“帮助”菜单之后
• 时间滑块插件用于动画播放时序栅格和矢量数据，包括将地图上已有矢量图层绑定到时间轴，以及绘制栅格堆叠中采样像素值随时间变化的像素时序图
• 大气效果插件渲染深空背景、视差星空、彗星，以及低缩放级别下地球周围的大气光晕（技术改编自 Leonel Dias),，含旋转地球面板及可自定义大气光晕和深空颜色
• 路线插件通过 maplibre-gl-directions: 提供交互式路线规划：点击地图添加航点、拖拽 reposition、点击航点移除（使用公共 OSRM 演示服务器，仅驾车）
• 在桌面和 Web 上均可从上传的 zip 安装外部插件，另支持从应用数据 plugins 目录和本地开发插件目录加载外部插件 zip，“管理插件”列表按字母排序
• public/plugins/<id>/ 下的捆绑即插即用插件，烘焙进 Web 和桌面构建并自动加载，无需 manifest URL
• 浏览器部署支持 Docker、嵌入友好 URL 参数（包括 ?url= 项目深链接以跳过欢迎向导，以及 ?welcome=0 参数以退出引导），以及 maponly 无 chrome 模式
• 基于同一代码库使用 Tauri v2 mobile 构建的原生 Android 应用，通过 GitHub Actions 工作流生成按架构签名的 APK（约 40 MB）；依赖本地桌面进程的工具（Whitebox、Raster、Conversion、AI Segmentation、PostgreSQL/Martin）在移动端隐藏，不显示无法运行的功能。参见 Android
• 可安装、支持离线的渐进式 Web 应用（PWA）构建，以及下载离线区域工具，可预缓存当前地图视图的底图瓦片；service worker 缓存 CDN 加载的 Pyodide 和 PGlite/PostGIS 引擎，使浏览器 SQL 和 Python 在首次使用后仍可离线工作
• 国际化框架采用 react-i18next 和 13 套完整的按构建翻译目录，以及 ?locale/?lang 查询参数用于设置嵌入语言
• 无障碍适配：axe 检查的界面、键盘导航和屏幕阅读器标签
• 应用级、区块级和插件级 React 错误边界，可隔离故障并保持工作区其余部分可用
• Python 包（geolibre），将完整应用以 anywidget, 嵌入 Jupyter notebook，提供扩展的 leafmap 风格 API（本地栅格、标记/聚类和 choropleth 图层；split_map、add_legend 和 add_colorbar 辅助函数；所选/绘制要素的类型化读回；以及 to_html 导出）和双向项目同步
• 可选 Python FastAPI sidecar，用于更重的处理工作流

前置要求

• Node.js 22+
• Rust 工具链（rustup))，用于 Tauri 桌面版构建
• Linux：webkit2gtk、libayatana-appindicator（参见 Tauri 前置要求)

安装

Linux、Windows 和 macOS 的预构建桌面安装包发布在 Releases 页面。在 Windows 上，可通过 Microsoft Store, 安装经签名的自动更新版本，或通过 winget install OpenGeos.GeoLibre 安装未签名的 GitHub Release 版本。在 macOS 上，可使用 Homebrew 安装并更新 — GeoLibre 已在官方 Homebrew Cask 仓库中提供，无需添加 tap：

brew install --cask geolibre

macOS 应用使用 Apple Developer ID 证书签名并经 Apple 公证，因此可正常启动，无需隔离属性变通方法。详见 Downloads 了解详情及手动安装步骤。

若要从源码构建：

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install

Bun 用户可运行 bun install。根目录 trustedDependencies 列表允许 core-js、@google/genai 和 protobufjs 的已知安装脚本。

更新

将现有源码检出更新到最新版本时，拉取变更、重新安装依赖（以防 package.json 有变动），然后重新构建：

cd /path/to/GeoLibre   # your GeoLibre checkout
git pull origin main
npm install            # or: bun install

若运行生产构建，之后请用 npm run build（Web）或 npm run tauri:build（桌面）重新构建。若使用开发服务器（npm run dev 或 npm run tauri:dev），上述 git pull 和 npm install 已足够 — 只需重启开发服务器即可加载变更。

运行（Web 开发，浏览器中的地图）

npm run dev

打开 http://localhost:5173.。地图与浏览器矢量导入支持 DuckDB-WASM Spatial 可读取的本地矢量文件，包括 GeoJSON、GeoParquet、GeoPackage、Shapefile、FlatGeobuf、KML/KMZ、GML 等常见格式，并直接处理 GeoJSON、压缩 Shapefile 和 KMZ 压缩包。可通过「添加矢量图层」选择文件，或拖放到应用中。GeoTIFF/COG 栅格也可拖放到地图上作为栅格图层。桌面文件系统对话框、本地 MBTiles 和本地栅格文件读取需要 Tauri。

使用 Docker 运行

构建并运行 GeoLibre 的浏览器版本：

docker build -t geolibre .
docker run --rm -p 8080:80 geolibre

打开 http://localhost:8080.。Docker 镜像通过 nginx 提供生产版 Vite 构建。仅桌面端功能（如 Tauri 文件系统对话框、本地 MBTiles、本地栅格文件读取、项目保存/打开）需要桌面应用。

捆绑的转换 sidecar

镜像还捆绑了 Python 转换/Whitebox sidecar（uvicorn），并在 /sidecar 反向代理，使浏览器可通过同源访问，无需处理 CORS 或单独进程。/conversion/status 可通过 http://localhost:8080/sidecar/conversion/status 访问。

• 矢量 → GeoParquet 和 CSV → GeoParquet 在浏览器中通过 DuckDB-WASM 运行，无需 sidecar。
• 矢量 → FlatGeobuf、矢量 → PMTiles 和 栅格 → COG 使用 sidecar。这些操作读取 sidecar 文件系统上的文件路径，因此在纯浏览器环境中，目前仅适用于挂载到容器中的文件（浏览器无法向容器传递绝对路径）；基于上传的输入为计划中的后续功能。桌面应用传递真实的本地路径，因此所有转换均可使用。
• 容器中的 PMTiles 和 Whitebox 仅支持 amd64 — freestiler 和 whitebox-workflows 未发布 linux/arm64 wheels。在 arm64 上其他转换仍可用；这两项会报告不可用。

由于 sidecar 可通过同源访问，转换读写限制在 GEOLIBRE_CONVERSION_ROOTS（镜像中默认为 /data）。将文件挂载到该目录：

docker run --rm -p 8080:80 -v "$PWD/data:/data" geolibre

设置 GEOLIBRE_DISABLE_SIDECAR=1 仅运行 nginx（原始仅 Web 行为）：

docker run --rm -p 8080:80 -e GEOLIBRE_DISABLE_SIDECAR=1 geolibre

密码保护（可选）

设置 GEOLIBRE_AUTH_USER 和 GEOLIBRE_AUTH_PASSWORD，将整个容器（应用及 /sidecar API）置于 HTTP Basic Auth 之后：

docker run --rm -p 8080:80 \
  -e GEOLIBRE_AUTH_USER=admin \
  -e GEOLIBRE_AUTH_PASSWORD='change-me' \
  geolibre

浏览器在首次访问时会提示输入凭据。/healthz 保持未认证，以便容器健康检查继续工作。变量未设置时（默认），不启用认证。

与任何 Docker 环境变量一样，通过 -e 传入的密码会留在 shell 历史中，并可通过主机上的 docker inspect 读取。除快速本地测试外，建议使用带权限限制文件的 --env-file，或密钥管理器。

这是单一共享凭据，而非按用户账户。Basic Auth 会在每次请求中发送凭据，因此在可信本地网络之外，应在容器前放置 TLS 终止反向代理（Caddy、Traefik、nginx）。若需多用户或 SSO，可在未修改的镜像前使用 oauth2-proxy 或 Authelia 等认证代理。另请参阅 docker/nginx.conf 中关于在公开暴露镜像前移除 localhost CSP 许可的说明。

已发布镜像可从 GitHub Container Registry 获取：

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

若在 URL 子路径下部署，请在构建时传入 GEOLIBRE_APP_BASE：

docker build --build-arg GEOLIBRE_APP_BASE=/geolibre/ -t geolibre .

容器始终从根路径提供应用。构建参数仅设置应用期望的 URL 前缀，因此子路径部署还需在容器前放置反向代理，在转发请求前剥离前缀（例如 nginx proxy_pass http://geolibre/;，末尾带斜杠）。

SQL 工作区

SQL 工作区在浏览器中针对已加载图层和远程数据直接运行 DuckDB SQL（已加载 Spatial 扩展，因此可使用 ST_* 函数）。从 Processing 菜单打开。

• 查询已加载图层。 每个含内存要素的矢量图层都会暴露为表；可查询的表名列在对话框顶部。
• 读取文件和 URL。 使用 read_parquet()、read_csv_auto()、read_json_auto() 或 ST_Read()。FROM/JOIN 后的裸 URL 或路径（例如 SELECT * FROM https://host/data.parquet）会自动包装为匹配的读取器。远程文件通过 HTTP 范围请求流式传输，因此不会完整下载大型数据集。
• 示例查询。 下拉菜单提供针对公开示例数据集的可直接运行示例（仅属性、聚合和空间查询），以及按图层的「图层示例查询」下拉菜单。
• 查询历史。 最近运行的查询会保存（在 localStorage 中），可从 History 下拉菜单重新加载。
• 结果与导出。 结果以网格显示（显示有上限；完整结果保留用于导出）。查询返回几何列时，可将结果作为新图层添加到地图（可自定义图层名称），或导出为 CSV 或 GeoParquet。

SELECT NAME, CONTINENT, POP_EST, geom
FROM https://data.source.coop/giswqs/opengeos/countries.parquet
WHERE POP_EST > 50000000
ORDER BY POP_EST DESC;

每次运行仅支持单条语句。云对象存储 URL（s3://、gs://、az://）会透明重写为对应的公共 HTTPS 等价地址，因此可用于匿名/公开数据集。

矢量工具

Processing → Vector 菜单打开统一的矢量工具对话框，提供针对已加载 GeoJSON 图层的常见几何操作。选择工具、输入图层（双层工具还需叠加图层）、设置参数后，结果会作为新图层添加到地图。

• 几何工具。 Buffer（缓冲区）（按公里、米或英里指定距离）、Centroids（质心）（每个要素一个质心点）、Convex hull（凸包）（用单个多边形包裹所有要素）、Dissolve（融合）（合并多边形，可按属性字段分组）、Bounding box（边界框）（所有要素的矩形外包）、Simplify（简化）（Douglas-Peucker 顶点削减）、Smooth（平滑）（基于样条的线/多边形平滑）、Regular grid（规则网格）（在范围内生成点或多边形网格），以及 Voronoi / Delaunay（从点图层生成 Voronoi 多边形或 Delaunay 三角剖分）。
• 叠加工具。 Clip（裁剪）（按叠加图层裁剪输入，保留输入属性）、两个多边形图层之间的 Intersection（相交）、Difference（差异） 和 Union（联合）。
• 连接工具。 Spatial join（空间连接）（按空间关系——intersects、within 或 contains——将连接图层的属性附加到每个输入要素，支持 inner 或 left join，适用于任意几何类型）和 Attribute join（属性连接）（按匹配键字段将连接表的属性附加过来，不涉及几何——例如将普查统计连接到边界多边形——可选择要带入的字段，支持 inner 或 left join）。
• 选择工具。 Select by value（按值选择）（提取属性满足条件的要素——=、≠、>、≥、<、≤、contains、starts with、is empty/not empty）和 Select by location（按位置选择）（按与第二层要素的空间关系——intersects、within、contains 或 disjoint——提取要素并输出到新图层）。
• 三种引擎。 所有工具均可通过 Turf.js, 在浏览器中完整运行，因此无需 sidecar。所有工具也可在可选的 GeoPandas sidecar 上运行以获得支持投影的结果；当 sidecar 不可用时，对话框会回退到客户端引擎。第三种 Python (Pyodide) 引擎通过 Pyodide 运行与 sidecar 相同的 GeoPandas/Shapely 代码，但完全在浏览器中执行——无需服务器，因此在 web 构建中也能使用。首次运行会从 CDN 惰性下载 Python 运行时（可通过 VITE_PYODIDE_INDEX_URL 覆盖以自托管，支持离线使用）；结果与 sidecar 一致，因为两者共享同一 vector_ops.py。

要启用 sidecar 引擎，请安装可选的 vector 扩展（默认不捆绑，以保持 sidecar 体积较小）：

# install the vector extras (GeoPandas, Shapely)
pip install -e "backend/geolibre_server[vector]"
# run it
geolibre-server   # or: uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

栅格工具

Processing → Raster 菜单会打开一个统一的栅格工具对话框，提供常用栅格操作。由于栅格处理无法在浏览器中运行，这些工具在 Python sidecar（rasterio）上执行，采用文件路径输入、文件路径输出：选择工具、指定输入栅格和输出文件、设置参数，然后运行任务。

• 地形。 从高程模型生成 Hillshade（山体阴影）、Slope（坡度）（度或百分比）和 Aspect（坡向）。
• 重投影。 Reproject（重投影） 到目标 CRS，以及 Resample（重采样） 到新的像元大小，可选择重采样方法（nearest、bilinear、cubic）。
• 裁剪。 Clip by extent（按范围裁剪）（栅格 CRS 中的边界框）和 Clip by mask layer（按掩膜图层裁剪）（GeoJSON 掩膜，会自动重投影到栅格）。
• 栅格转矢量。 Polygonize（面化）（按像元值分组的矢量多边形）和 Contour（等高线）（从高程模型生成等高线），输出为 GeoJSON。
• 矢量转栅格。 Interpolation (IDW / Kriging)（插值） 通过反距离加权或普通克里金，将点图层的数值属性转换为连续栅格表面。

这些工具共用 conversion sidecar 任务运行器。请安装可选的 raster 扩展（rasterio 也会由 conversion 扩展一并拉取）：

# install the raster extras (rasterio, numpy, contourpy)
pip install -e "backend/geolibre_server[raster]"
# run it
geolibre-server   # or: uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

AI 分割

Processing → AI Segmentation 对话框借助 segment-geospatial（SamGeo）和 Meta 的 SAM 3 模型，将影像转换为矢量要素：选择 GeoTIFF，输入文本提示（例如 "trees"、"buildings"、"water"）或运行自动分割，生成的多边形会作为新图层添加。

模型栈不在 sidecar 内部运行。sidecar 会在独立的 samgeo-api 服务器（segment-geospatial 附带的 REST 服务器）前暴露一个轻量 /ml 反向代理，由该服务器运行 SAM 3 并返回 GeoJSON。强烈建议使用 CUDA GPU。

# install the model server (in an env with a working PyTorch build)
pip install "segment-geospatial[api,samgeo3]"
# install the sidecar's ml extra (just an HTTP client; models live in samgeo-api)
pip install -e "backend/geolibre_server[ml]"

当 samgeo-api 位于 PATH 上时会按需启动，也可通过 GEOLIBRE_ML_SAMGEO_URL=http://127.0.0.1:8000 将 sidecar 指向现有服务器。详见 docs/user-guide/segmentation.md。使用 SAM 3。

嵌入演示

浏览器演示支持 URL 参数，便于 iframe 友好布局。

通过 URL 打开项目：

https://web.geolibre.app/?url=https://share.geolibre.app/giswqs/3d-tiles.geolibre.json

支持的查询参数：

Parameter	Example	Description
url	url=https://share.geolibre.app/giswqs/3d-tiles.geolibre.json	从公共 URL 加载 .geolibre.json 项目。
layout	layout=compact	使用紧凑嵌入布局，工具栏按钮仅显示图标，并隐藏项目元数据。embed 和 iframe 为别名。
toolbar	toolbar=icons	仅显示图标工具栏按钮，但不启用完整紧凑布局。
panels	panels=none	隐藏图层、样式和属性表面板。hidden、hide 和 off 为别名。
hidePanels	hidePanels=true	隐藏图层、样式和属性表面板的另一种方式。
maponly	maponly	隐藏所有界面元素（工具栏菜单、图层/样式/属性面板和状态栏），仅保留地图。bare 标志或 true、1、yes、on 中的任意一个均可启用。
theme	theme=dark	设置加载时的初始颜色主题，覆盖操作系统偏好。接受 dark 或 light；应用内切换此后仍可使用。

窄版嵌入请使用紧凑模式。这会显示仅图标的工具栏按钮并隐藏项目元数据：

https://web.geolibre.app/?url=https://share.geolibre.app/giswqs/3d-tiles.geolibre.json&layout=compact

面向地图的嵌入可隐藏图层、样式和属性表面板：

https://web.geolibre.app/?url=https://share.geolibre.app/giswqs/3d-tiles.geolibre.json&layout=compact&panels=none

若仅需图标工具栏按钮，请使用 toolbar=icons。panels=hidden、panels=hide、panels=off 和 hidePanels=true 是隐藏面板的可接受别名。

若要完全无界面、仅显示地图的嵌入，请使用 maponly。它会隐藏工具栏菜单、所有面板和状态栏：

https://web.geolibre.app/?url=https://share.geolibre.app/giswqs/3d-tiles.geolibre.json&maponly

Python 软件包（Jupyter）

GeoLibre 提供了一个 Python 软件包，可将完整的 GeoLibre 应用（菜单、面板、处理工具）以 anywidget, 的形式嵌入 Jupyter notebook 单元格，并提供 leafmap 风格的 API。状态通过单个 .geolibre.json 项目在双向同步，因此你从 Python 添加的数据会出现在 UI 中，而你在 UI 中所做的编辑也可在 Python 中读回。

pip install geolibre

或使用 conda：

conda install -c conda-forge geolibre

from geolibre import Map

m = Map(center=(-100, 40), zoom=4)
m.add_geojson("https://example.com/data.geojson", name="Data")
m.add_tile_layer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", name="OpenStreetMap")
m.add_cog("https://example.com/dem.tif", name="DEM")
m  # the full GeoLibre UI renders in the cell

读取在 UI 中编辑的状态，并进行项目往返：

m.to_project()["mapView"]["center"]   # reflects the live UI view after panning
m.save_project("my-map.geolibre.json")
Map().load_project("my-map.geolibre.json")

软件包源码位于 python/，捆绑的 Web 应用由 npm run build:embed 构建进 wheel。交互式组件可在本地 Jupyter、VS Code、Google Colab（自动使用其内置端口代理）以及 JupyterHub / 远程服务器（通过随 wheel 捆绑、安装时自动启用的 Jupyter Server 扩展；因此托管式 Hub 无需 jupyter-server-proxy；非 Hub 远程环境请传入 Map(server_proxy=True)）中运行。完整 API 请参阅 Python 软件包指南。

环境变量

街景插件可使用 Google Street View 和 Mapillary 影像。创建 apps/geolibre-desktop/.env.local 并设置一个或两个提供商的凭据：

VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
VITE_MAPILLARY_ACCESS_TOKEN=your_mapillary_access_token

对于 Google Street View，请在 Google Cloud 中为该密钥启用 Maps Embed API。对于 Mapillary，请在 Mapillary 开发者控制台创建应用并使用其客户端访问令牌。

可选的 Cesium 三维地球视图 — 与 2D MapLibre 地图并排显示、由 CesiumJS 渲染的分屏地球 — 需要 Cesium Ion 访问令牌以加载全球影像与地形。创建免费的 Ion 账户，复制默认访问令牌，并在构建时设置：

CESIUM_TOKEN=your_cesium_ion_access_token

CESIUM_TOKEN（或带 VITE_ 前缀的 VITE_CESIUM_TOKEN）由 vite.config.ts 读取并写入构建。用户还可在设置对话框的环境变量部分在运行时设置（无需重新构建），该部分提供专用的掩码 Cesium Ion token 字段。该令牌保存在设备本地（Web 构建中为浏览器存储），不会写入共享项目文件，并会覆盖构建时值；Web 用户可借此使用自己的 Ion 令牌。（同一区域中的自由格式 VITE_CESIUM_TOKEN 变量仍可用，并作为覆盖优先生效。）若没有任何来源的令牌，三维地球开关将完全隐藏（2D 地图不受影响）。Ion 访问令牌设计为可打包进客户端 bundle。地球视图集成方式见 docs/architecture.md。

可选的 Python（Pyodide） 向量引擎默认从公共 jsDelivr CDN 加载运行时。若要在离线或生产环境中自托管，请将其指向 Pyodide 发行版的镜像副本：

VITE_PYODIDE_INDEX_URL=https://your-host/pyodide/v0.27.7/full/

同样，DuckDB Spatial 扩展默认从 DuckDB 远程扩展仓库安装。若要从镜像加载（从而跳过 INSTALL spatial 并直接加载扩展），请设置扩展文件的完整路径或 URL：

VITE_DUCKDB_SPATIAL_EXTENSION_PATH=https://your-host/duckdb/spatial.duckdb_extension.wasm

VITE_PYODIDE_INDEX_URL 与 VITE_DUCKDB_SPATIAL_EXTENSION_PATH 也可通过设置对话框的运行时环境变量在运行时设置（无需重新构建），因此隔离网络或企业部署可将 Pyodide 与 DuckDB Spatial 扩展指向内部镜像而无需重新构建。

更改这些值后请重启 npm run dev 或 npm run tauri:dev。Vite 仅将带 VITE_ 前缀的变量暴露给前端。

运行（桌面版）

npm run tauri:dev

构建

npm run build
npm run tauri:build

默认桌面构建保持 Linux 二进制体积较小，并使用 DuckDB-WASM 实现基于 DuckDB 的浏览器功能。若要构建启用原生 duckdb-rs 向量加载器的更大桌面二进制，请运行：

npm run tauri:build:native-duckdb

输出位置：

• Web 构建 — apps/geolibre-desktop/dist/ 中的静态文件。使用任意静态 Web 服务器（或上方的 Docker 镜像）提供该目录。
• 桌面安装包 — apps/geolibre-desktop/src-tauri/target/release/bundle/，按平台分子目录：Linux 为 deb/、rpm/ 和 appimage/；Windows 为 msi/ 和 nsis/；macOS 为 dmg/ 和 macos/。未打包的可执行文件位于 apps/geolibre-desktop/src-tauri/target/release/。在 Linux 上，npm run tauri:build 默认构建 deb 与 rpm；传入 --bundles 会替换而非追加该默认选择，因此请列出你需要的所有格式，例如 npm run tauri:build -- --bundles deb,rpm,appimage 可一次包含三种。

Android

GeoLibre 通过 Tauri v2 mobile 从同一代码库构建为原生 Android 应用。你需要 Android SDK + NDK、JDK（17 或 21）以及 Rust Android 目标；完整工具链配置、签名与侧载指南见 docs/android.md。配置完成后：

cd apps/geolibre-desktop
npx tauri android init                          # generate the Gradle project (once)
npm run tauri android dev                        # run on a connected device/emulator
npx tauri android build --apk --split-per-abi    # release APKs, ~40 MB per ABI

在真机上安装 arm64-v8a APK。CI 工作流（.github/workflows/android.yml）在每次发布的 GitHub release 时（也可通过 “Run workflow” 按钮按需触发）构建并签署各 ABI 的 release APK，并上传为构件；设置 ANDROID_KEYSTORE_* 仓库密钥以使用正式 release 密钥签名（否则使用 debug 密钥生成可测试构建）。需要 Python sidecar 或本地辅助进程的重型工具在移动端会隐藏。

质量检查

运行快速的 TypeScript 单元测试：

npm run test:frontend

运行完整的本地质量门禁：

npm run ci

可选 Python sidecar

cd backend/geolibre_server
python -m venv .venv && source .venv/bin/activate
pip install -e .
uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

转换工具（Processing → Conversion）

Processing → Conversion 菜单（Vector → GeoParquet / FlatGeobuf、CSV → GeoParquet、Vector → PMTiles、Raster → COG）通过 http://127.0.0.1:8765 与该 sidecar 通信。Vector → GeoParquet 与 CSV → GeoParquet 也可在浏览器中完全通过 DuckDB-WASM 运行，无需 sidecar；其余功能需要 sidecar。

若要在 Web 构建中使用这些功能，请启动 sidecar 并从 localhost:5173 提供应用（CORS 限制为该来源及 Tauri 来源）：

# install the conversion extras (DuckDB, rio-cogeo, freestiler)
pip install -e "backend/geolibre_server[conversion]"
# run it
geolibre-server   # or: uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

sidecar 在首次使用时会自举托管运行时；设置 GEOLIBRE_CONVERSION_PYTHON=$(which python) 可改为复用当前环境。详情见 backend/geolibre_server/README.md。

仓库布局

apps/geolibre-desktop   # Tauri + React app
packages/core           # Types, store, project format
packages/map            # MapLibre integration
packages/ui             # Tailwind + shadcn/ui
packages/plugins        # Plugin API
packages/processing     # Algorithm registry
backend/geolibre_server # FastAPI sidecar
python/                 # geolibre Python package (Jupyter anywidget)
docs/                   # Architecture & API docs

添加插件

内置插件位于 packages/plugins/src/plugins/，由桌面应用在 apps/geolibre-desktop/src/hooks/usePlugins.ts 中注册。地图控件插件可通过 getMapControlPosition() 和 setMapControlPosition() 暴露控件位置，以便“插件”菜单能在地图四角之间移动它们。

对于外部插件开发，可从 GeoLibre 插件模板. 入手。它包含 plugin.json 清单、GeoLibre 插件封装入口点，以及一个 package:geolibre 脚本，用于为桌面应用数据目录 plugins/ 创建 zip 文件。开发期间，设置 → 管理插件 可扫描额外的本地插件目录，包括未打包的 bundle 文件夹（例如模板的 geolibre-plugin/ 目录）或托管的 plugin.json 清单 URL。外部插件契约请参阅 Plugin API。

要将外部插件内嵌（bake）到构建中以便自动加载——无需“设置”项和清单 URL——将其构建后的文件夹放入 apps/geolibre-desktop/public/plugins/<plugin-id>/（与清单 URL 会提供的 plugin.json + dist/ 相同）。bundledPlugins() Vite 插件会在构建时发现它，应用通过常规的外部插件路径加载。同一文件夹同时服务于 Web 构建和桌面构建（两者使用相同前端），因此一次放入即可覆盖两者。该文件夹下的私有插件 bundle 会被 git 忽略，并在构建/部署时复制进来。详情与安全模型请参阅 Plugin API。

1. 在 packages/plugins/src/plugins/ 中创建插件文件。

import type { GeoLibreAppAPI, GeoLibrePlugin } from "../types";

export const myPlugin: GeoLibrePlugin = {
  id: "my-plugin",
  name: "My Plugin",
  version: "0.1.0",
  activate: (app: GeoLibreAppAPI) => {
    app.setBasemap("https://example.com/style.json");
  },
  deactivate: () => {},
};

2. 从 packages/plugins/src/index.ts 导出。

export { myPlugin } from "./plugins/my-plugin";

3. 在 apps/geolibre-desktop/src/hooks/usePlugins.ts 中注册。

import { myPlugin } from "@geolibre/plugins";

manager.registerAll([
  maplibreLayerControlPlugin,
  maplibreGeoAgentPlugin,
  maplibreGeoEditorPlugin,
  myPlugin,
]);

插件可使用应用 API 更换底图、添加 GeoJSON 图层或挂载 MapLibre 控件。对于 MapLibre 控件插件，添加包依赖，在 apps/geolibre-desktop/src/main.tsx 中导入其 CSS，然后在 activate() 中调用 app.addMapControl(control, "top-left")，并在 deactivate() 中调用 app.removeMapControl(control)。

内置 MapLibre 控件（如 Navigation、Fullscreen、Geolocate、Globe、Terrain、Scale、Attribution 和 Logo）可从桌面应用的“控件”菜单切换。同一菜单还打开 Search——由 Components 插件支持的独立地点搜索面板。对于 Layer Control 和 Components 等项目特定控件，若使用插件 API 或需要插件生命周期行为，请保留在插件菜单中。

Components 插件封装 maplibre-gl-components 控件，并将其图层事件接入 GeoLibre store。它为 FlatGeobuf、PMTiles、Zarr、LiDAR 和 Gaussian splats 提供“添加数据”快捷方式；栅格 COG 和 GeoTIFF 图层也可通过标准“添加栅格图层”对话框添加。

若第三方 MapLibre 控件需要应用特定的样式修复，请在 apps/geolibre-desktop/src/index.css 中添加作用域覆盖，而非编辑 node_modules 中的文件。选择器应仅限于插件控件类。例如，GeoEditor 工具栏按钮需要本地覆盖，因为 MapLibre 默认控件按钮 CSS 可能覆盖其 flex 居中：

.geo-editor-control .geo-editor-tool-button {
  align-items: center;
  display: flex !important;
  justify-content: center;
  line-height: 0;
  padding: 0;
}

.geo-editor-control .geo-editor-tool-button svg {
  display: block;
  flex: 0 0 auto;
  margin: 0;
}

提交更改前运行检查：

npm run build
pre-commit run --all-files

文档

完整文档（含用户指南和教程）发布于 geolibre.app.

• 用户指南 - 针对界面、添加数据、图层、样式、属性表、地图控件、处理、SQL Workspace、数据集成、插件、设置和嵌入的逐功能参考。
• 教程 - 动手实践的端到端工作流:：制作首张地图、云原生数据、矢量分析、地形分析、空间 SQL，以及分享与嵌入。
• 参考
  • Architecture
  • Android
  • Project format
  • Plugin API
  • UI Profiles
  • Python package (Jupyter)
  • Roadmap
  • How to Cite

致谢

GeoLibre 建立在免费开源的地理空间与 Web 社区之上——包括 MapLibre GL JS、deck.gl、DuckDB-WASM Spatial、Turf.js、Tauri、React 等。完整项目与社区贡献者列表请参阅 致谢 页面。

• Atmosphere Effects 插件（深空背景、视差星空、彗星与地球大气光晕）借鉴了 Leonel Dias's 文章 Globe atmosphere, halo, and comets 的技术与视觉设计——分层 Canvas 2D 方法、光晕渐变与 "screen" 混合、在俯仰角下保持光晕对齐的 limb-sampling，以及星空/彗星参数。
• 社区贡献者 — 感谢 Ryanphoenix 的诸多宝贵贡献，包括问题报告、反馈与改进。
• Beta 测试者 — 感谢 René van der Velde（荷兰）的早期测试、详细错误报告与功能建议。

引用

若在研究中使用了 GeoLibre，请予以引用。GeoLibre 已在 Zenodo, 归档，每个版本都会生成 DOI。下方概念 DOI 始终解析为最新版本。

Wu, Q. (2026). GeoLibre: A lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. Zenodo. https://doi.org/10.5281/zenodo.20785400

也可使用 GitHub 的 "Cite this repository" 按钮（读取 CITATION.cff）复制现成的 APA 或 BibTeX 条目。更多格式请参阅 How to Cite 页面。

许可证

MIT