GeoLibre 云原生 GIS 实战指南：从第一张地图到分享嵌入的完整工作流

GeoLibre 云原生 GIS 实战指南：从第一张地图到分享嵌入的完整工作流

【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre

GeoLibre 是一个轻量级的云原生 GIS 平台，能在浏览器、桌面端、移动端和 Jupyter Notebook 中完成地理空间数据的可视化、探索与分析。本文不按"教程一二三"的顺序罗列，而是按你实际要解决的任务组织：快速出一张图、不下载就加载远程大数据集、做几何与地形分析、用 SQL 查数上图，最后把成果发布并嵌入网页。跟着任务走，你就能从空工作区一路做到可分享的分析成果。

动手前先分清：哪些功能在浏览器里就能跑，哪些离不开桌面端

🖥️ GeoLibre 同时有浏览器构建版（web.geolibre.app，无需安装任何软件）和桌面应用。两者的能力边界直接决定了你该在哪台设备上动手，官方文档也只在需要桌面端的步骤处做了单独标注：

💡 容易误解的一点：Whitebox 地理处理工具箱不需要桌面端——它的一千多个工具以 WebAssembly 形式直接在浏览器里运行。真正依赖桌面应用的只有本地文件读写和 Python 侧车相关的工具。

多个任务会反复用到同一份公开的世界各国 GeoParquet 示例数据集：

https://data.source.coop/giswqs/opengeos/countries.parquet

它的字段沿用 Natural Earth 命名（NAME、CONTINENT、POP_EST、GDP_MD_EST），几何列是geom。

如何几分钟内做出第一张带样式的地图

这是最快的上手路径，全程可以在在线版完成。

添加第一个矢量图层

1. 点击添加数据 → 矢量图层（Add Data → Vector Layer）。
2. 在弹出面板的 URL 输入框中粘贴上面那份countries.parquet的地址。
3. 点击加载（Load）。

加载完成后，国家边界会直接出现在底图上，同时图层面板里多出一个名为countries的图层。支持的数据源类型远不止矢量 URL，可查阅 添加数据参考。

给图层上色与做分级统计图

1. 在图层面板选中countries，展开右侧的样式面板（若折叠）。
2. 调整填充颜色、轮廓颜色和填充不透明度，地图会实时刷新。
3. 想按人口或 GDP 画分级统计图（choropleth）：把样式类型设为Graduated，选一个数值属性（如POP_EST或GDP_MD_EST），再挑类别数（Classes）、配色方案（Scheme）与色带（Colormap），最后点应用样式类型。此时每个分级会在色带下方列出对应颜色。

在属性表里检查数据

1. 点状态栏上的属性表展开，选中countries图层加载记录。
2. 按任意列排序，或在搜索属性框里输入关键词定位要素；选中某一行时，地图会同步高亮对应国家。
3. 点探索（Explore）可以一次性剖析每个字段的类型、完整度和值分布。
4. 还可以为该图层开启要素识别（Identify features），之后直接点击地图上的某个国家，弹窗即显示它的属性。

保存或发布

• 桌面端：项目 → 保存，写入一个.geolibre.json文件到本地。
• 任何环境：项目 → 分享，上传后得到一个公开链接（后面"发布与嵌入"一节会展开）。

如何不下载整个文件就加载远程 GeoParquet、FlatGeobuf 与 COG

☁️ GeoLibre 的卖点之一就是"为云原生格式而生"：矢量侧的 GeoParquet 与 FlatGeobuf、栅格侧的 Cloud-Optimized GeoTIFF（COG）、瓦片侧的 PMTiles，都能通过 HTTP 按需读取，而不是先把文件整个拖进内存。

流式加载远程 GeoParquet

GeoParquet 是压缩的列式矢量格式，天生适合 HTTP 读取：

1. 打开添加数据 → GeoParquet 图层（或矢量图层）。
2. 粘贴一个 GeoParquet 地址，例如示例数据集的 URL。
3. 勾选流式 GeoParquet（不拷贝）（Stream GeoParquet (no copy)）：它会改用 HTTP range 请求"原地查询"文件。这一模式对按空间排序（如 Hilbert 序）的大文件效果最好——GeoLibre 自带的转换工具写出的文件正是 Hilbert 序——因为这样只需要抓取当前查询涉及的那几个 row group。
4. 点击加载。

这套"按需读取"的能力由 duckdb-vector-loader.ts 基于 DuckDB-WASM 实现，tests/geoparquet-metadata.test.ts 与 tests/geoparquet-crs.test.ts 则从元数据解析和坐标系两个维度验证了读取管线的正确性。

加载 FlatGeobuf 与 COG

💡 不想走菜单？把本地 GeoTIFF 或 COG 文件直接拖到地图上，也会作为栅格图层添加。

把本地数据转换成云原生格式

转换工具都在处理 → GeoLibre 工具箱 → 转换下，但不同工具跑在不同引擎上：

以"把本地 GeoJSON 发布为 GeoParquet"为例：打开转换 → 矢量转 GeoParquet，选输入文件和输出路径，运行转换，再把生成的 GeoParquet 加回地图验证——数据没变、体积更小、还能被流式读取。

转换完的数据可以无缝接入后面的空间 SQL 查询（SQL 工作区能直接从 URL 读 Parquet、CSV、JSON、GeoJSON），也可以用时间滑块插件（Time Slider）对一串 COG 做时间动画，详见 数据集成。

如何做矢量分析：缓冲、叠加与属性挂接

本节完成一个小工作流：缓冲一个图层 → 与另一个图层叠加 → 检查结果 → 导出。工具都在处理 → GeoLibre 工具箱 → 矢量菜单下。

⚠️ 同一个菜单里藏着两个工具箱：处理 → 矢量（分隔线上方）是 Whitebox 目录的矢量类别；本任务要的是处理 → GeoLibre 工具箱 → 矢量里的对话框。选错菜单会打开完全不同的工具集。

第一步：准备输入

至少需要一个矢量图层；做叠加则需要两个，比如一组点/线要素加一个用于裁剪的多边形图层。

第二步：缓冲图层，注意引擎差异

打开处理 → GeoLibre 工具箱 → 矢量 → 缓冲，设置输入图层、距离、单位（公里、米、英里），然后选引擎：

点运行后，缓冲结果图层即被添加到地图上。

💡 为什么引擎会影响结果：客户端引擎在地理坐标（经纬度）里做缓冲，面积一大误差就明显。要在大范围区域内得到精确的公制距离，请选两个 GeoPandas 引擎之一——它们会先重投影再缓冲；其中 Python（Pyodide）引擎在 Web 构建版里也能用。

第三步：叠加与连接两个图层

有了缓冲结果（或任意多边形图层）和第二个图层，可在矢量菜单里选对应工具：

• 裁剪（Clip）：只保留输入中落在叠加图层内部的部分，并保留输入的属性。
• 相交（Intersection）：只留下两个多边形图层的重叠区域。
• 差异（Difference）：从输入中挖掉叠加图层覆盖的区域。
• 合并（Union）：两个多边形图层并成一个，任何引擎下都不保留属性。
• 空间连接（Spatial join）：按空间关系（相交、位于内部、包含）把连接图层的属性挂到每个输入要素上——典型用法是给每个点打上"包含它的那个多边形"的标签，适用于任何几何类型。
• 属性连接（Attribute join）：不碰几何，靠关键字段匹配挂接属性——例如通过共同的 FIPS 代码把人口普查统计挂到边界多边形上。它是一对一的（第一条匹配的连接行胜出），两侧各选关键字段，可选要带过来的字段列表，并选择内连接或左连接。

选好输入与叠加图层，点运行即可。

第四步：检查输出并复用

在结果图层上打开属性表核对属性，再调整样式让它与输入图层区分开。每次运行都会记入处理 → 历史：历史条目支持一键重跑，并且会复制等价的 Python 代码，方便你在脚本里复现同样的操作。

第五步：导出结果

要把输出存成云原生文件，走处理 → GeoLibre 工具箱 → 转换（如矢量转 GeoParquet、矢量转 FlatGeobuf）；也可以直接从属性表或 SQL 工作区导出记录。

如何从 DEM 派生山体阴影、坡度图与等高线

🏔️ 地形分析的任务是：给一个数字高程模型（DEM），产出山体阴影、坡度图和等高线。工具位于处理 → GeoLibre 工具箱 → 栅格。

先看引擎分工：哪些能在浏览器里跑

每个工具顶部都有引擎选择器，会显示当前环境可用的选项。对大栅格或地理坐标系（经纬度）下的地形数据，建议优先用侧车引擎。

加载 DEM

栅格工具是"文件进、文件出"，本地或可访问的栅格效果最好。添加一个 GeoTIFF 或 COG 格式的 DEM 图层即可。

生成山体阴影并叠到底图之上

1. 打开处理 → GeoLibre 工具箱 → 栅格 → 山体阴影。
2. 选 DEM 为输入，按需设置方位角（azimuth）、高度角（altitude）与 z 因子来调光照。
3. 运行后，着色浮雕栅格会作为新图层加入地图。把它拖到其他图层的下方，并把上层图层的混合模式设为正片叠底（Multiply）——这样地形起伏会从颜色里透出来；如果用降低不透明度的老办法，两个图层会被一起"洗淡"。

计算坡度与坡向

• 栅格 → 坡度：计算每个像元的陡峭程度。
• 栅格 → 坡向：计算最陡下降方向的罗盘方位。

任选其一运行后，用色带（colormap）给输出上色，再从地图上的控件菜单打开色条（Colorbar）显示数值标尺。

生成等高线

1. 打开栅格 → 等高线（Contour）。
2. 选 DEM，设置间距（interval，即相邻两条线之间的高程差）。
3. 运行后得到矢量格式的等高线图层，可以像任何矢量数据一样加标注、改样式。

⚠️ 等高线没有客户端引擎，只跑在 Python 侧车上，所以这一步必须用桌面应用。

裁剪到研究区

想把输出限制在特定区域：栅格 → 按范围裁剪（Clip by extent，边界框方式，浏览器也能跑）或按掩膜图层裁剪（矢量掩膜，仅侧车）。

后续可以再用栅格转矢量（Polygonize）把栅格输出变成矢量，或写出栅格转 COG方便分享；栅格序列的时间动画同样交给时间滑块插件。

如何用 DuckDB 空间 SQL 查询数据并直接上图

📊 从处理 → SQL 工作区打开 SQL 工作区。它基于 DuckDB-WASM 运行，所以浏览器和桌面应用里都可用，空间扩展也默认加载——所有ST_*函数开箱即用。

查询已加载的图层

每个已加载的矢量图层就是一张可查询的表。先按前面的步骤加载countries图层，然后运行：

SELECT NAME, CONTINENT, GDP_MD_EST FROM countries ORDER BY GDP_MD_EST DESC LIMIT 10;

点运行，结果表里就是预估 GDP 最高的十个国家。

💡 换数据集时列名会不同。不确定字段时先跑DESCRIBE SELECT * FROM '你的文件URL'看结构，比猜列名快得多。

直接查询远程文件：URL 就是表名

不用先加载文件——工作区会识别FROM子句里的裸 URL，自动包上正确的读取器，再通过 HTTP range 请求流式读取，全程不整体下载：

SELECT COUNT(*) AS n FROM https://data.source.coop/giswqs/opengeos/countries.parquet;

这是 SQL 工作区的专属便利写法；在标准 DuckDB CLI 里你得显式写read_parquet('https://...')。其按需读取逻辑与流式 GeoParquet 同源（duckdb-vector-loader.ts），相关行为由 tests/sql-query-layer.test.ts 等测试覆盖。

用空间函数做分析

-- 数据位于 EPSG:4326，面积单位是平方度； -- 排序结论有效，但要平方千米请用 ST_Area_Spheroid(geom) / 1e6。 SELECT NAME, ST_Area(geom) AS area, geom FROM https://data.source.coop/giswqs/opengeos/countries.parquet WHERE CONTINENT = 'Africa' ORDER BY area DESC;

注意保留geom列——这是结果能上图的前提。

结果上图与导出

当查询返回几何列时，点添加为图层即可从结果创建新图层（可顺手命名）。结果图层与普通矢量图层一样支持识别、选择和属性表，还能一次添加多个结果图层。导出 CSV与导出 GeoParquet按钮就在添加为图层旁边，查询结果可直接落地为文件。

💡 卡住了就用示例查询菜单从一个可运行的查询起步，或用历史重跑之前的查询。

如何把项目发布为公开链接并嵌入到网页

地图做完后的最后一步是分发。GeoLibre 的分享走share.geolibre.app，需要一次性配置个人 API 令牌。

配置分享令牌（只做一次）

1. 打开设置 → 环境变量。
2. 把令牌粘贴到Share.GeoLibre API token字段（令牌在 share.geolibre.app/settings 的"设置 → API 令牌"处创建）。

分享项目

1. 先摆好地图：图层、样式都弄好，把视图停在希望观众第一眼看到的位置。
2. 打开项目 → 分享...。
3. 确认标题并上传，返回一个指向.geolibre.json的公开 URL，例如：

https://share.geolibre.app/you/my-map.geolibre.json

分享文件捕获的内容与本地保存完全一致：图层、样式、插件状态、地图视图。唯一例外是读取你电脑上本地文件的图层——分享前对话框会把它们列为缺失，因为share.geolibre.app只存项目文件，绝不替你上传数据文件。本地数据需要先托管到公网（参见 项目文档 - 分享本地数据）。

用 url 参数打开分享的项目

任何人都可以把项目 URL 作为url参数传给在线版：

https://web.geolibre.app/?url=https://share.geolibre.app/you/my-map.geolibre.json

用 iframe 嵌入页面，并用参数控制界面外壳

一个干净的纯地图嵌入长这样：

<iframe src="https://web.geolibre.app/?url=https://share.geolibre.app/you/my-map.geolibre.json&amp;maponly" title="GeoLibre map" width="100%" height="600" style="border: 0;" loading="lazy" allow="fullscreen; geolocation" ></iframe>

常用外观参数（可自由组合）：

完整参数表（含data、style、tool深链等）见 嵌入与分享参考。

进阶：从你的页面在运行时驱动地图

URL 参数只在加载时生效一次。要在运行时持续对话——飞到用户在你自己界面里点击的记录、监听图内的操作——安装类型化客户端：

npm install @geolibre/embed

import { connect } from "@geolibre/embed"; const map = await connect(document.querySelector("iframe"), { origin: "https://web.geolibre.app", }); map.on("selectionChanged", ({ featureIds }) => showRecordFor(featureIds[0])); async function focusField(field) { await map.setView({ bbox: field.bbox }); await map.highlightFeature({ layerId: "fields", filter: { parcel_id: field.id }, fit: true }); }

这个客户端由 packages/embed/ 提供，配套契约见 tests/embed-api.test.ts。

⚠️ 运行时 API默认关闭：它只对你的页面源（origin）加入白名单的部署生效。web.geolibre.app本身没有开放白名单，所以这套接口面向你自己托管的构建版（Docker 镜像设GEOLIBRE_EMBED_ORIGINS环境变量即可开启）。不想引依赖的话，文档里也记录了免依赖的原始postMessage协议。

官方录制的演示视频：按主题挑选着看

文字之外，官方维护了一组从旧到新的实操录屏（收录于 视频教程），每篇都有分章节索引和摘要，可与上文任务对照：

高频问题速查

哪些操作必须用桌面应用？打开/保存项目文件、读取本地 MBTiles 与栅格、Python 侧车工具（rasterio 栅格处理；等高线；按掩膜裁剪；矢量转 FlatGeobuf / 矢量转 PMTiles / 栅格转 COG 等转换）。Whitebox 工具箱不在此列——它靠 WebAssembly 在浏览器里跑。

矢量缓冲选哪个引擎？客户端（Turf.js）零配置适合快速出图；要精确公制距离（尤其大范围区域）选侧车（GeoPandas，桌面）或 Python（Pyodide，任意环境）。

COG 序列怎么动起来？配合时间滑块插件做时间动画，参见 数据集成。

嵌入参数能随便组合吗？可以。maponly、layout=viewer、layout=compact、toolbar=none、panels=none、theme=dark彼此独立，按需叠加即可。

收尾：把六段任务串成一条线

回到任务视角看，整条链路是：出图（添加图层 + 样式 + 属性表）→喂数据（流式读取云原生格式、本地数据转换）→加工（矢量叠加与 DEM 地形派生）→问数（DuckDB Spatial SQL 上图与导出）→分发（分享链接 + 嵌入参数 + 运行时 API）。先从浏览器在线版零安装走一遍，遇到需要本地文件或侧车的步骤再切桌面应用，就能以最低成本跑通 GeoLibre 的完整工作流。

【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre