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 平台，能把地理空间数据加载、分析、加工和发布一气呵成，并且直接在浏览器里运行，数据不离开你的机器。本指南面向第一次接触它的人，带你走完一条完整工作流。

能力全景：先看 GeoLibre 能帮你做什么

动手之前：环境与安装差异

• 在线版：浏览器构建版（web.geolibre.app）打开即用，本章绝大多数操作都能在这里完成。
• 桌面应用：Windows、macOS、Linux 都有安装包。以下操作只能在桌面端做：打开/保存本地项目文件、读取本地 MBTiles 和栅格文件、Python 侧车（sidecar）工具（rasterio 栅格处理、栅格转 COG、矢量转 FlatGeobuf/PMTiles 等）。
• 不用装任何东西的例外：Whitebox 地理处理工具箱的 1000+ 工具以 WebAssembly 形式跑在浏览器里，在线版同样可用。

多个章节共用的示例数据是一份公开的世界国家 GeoParquet 文件，后续会反复用到：

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

💡小贴士：先用在线版把整条流程跑一遍，碰到需要本地文件再装桌面应用，能省不少时间。

第一张地图：从空工作区到可检查的样式化地图

目标：几分钟后得到一张"有数据、有样式、属性可查"的地图。

1. 打开应用：在线版直接开浏览器，桌面端启动应用。你看到的是一张底图 + 空的图层面板（Layers panel）。
2. 加一个图层：打开Add Data → Vector Layer，在矢量 URL 输入框里粘贴上面那份国家数据地址，点Load。地图上出现各国边界，图层面板多出countries图层。
3. 样式化：在图层面板选中countries，展开右侧样式面板，调整Fill color（填充色）、Outline color（轮廓色）、Fill opacity（填充不透明度）。想做分级统计图：把Style type设为Graduated，选一个数值字段（如POP_EST或GDP_MD_EST），再定Classes（类别数）、Scheme、Colormap，最后点Apply style type。
4. 检查数据：点状态栏的Attribute table展开属性表，选中countries加载记录。可以按列排序、在Search attributes里搜关键词（选中行会在地图高亮对应要素）；点Explore一次性查看每个字段的类型、完整度和值分布。再给图层打开Identify features，点击地图上的国家就能在弹窗看它的属性。
5. 保存或分享：桌面端用Project → Save写出一个.geolibre.json项目文件；任何环境都能用Project → Share上传拿到公开链接（见第 5 章）。

可观察的结果：地图上是按数值着色的国家多边形，属性表能查到 200 多条记录，点击国家弹属性。

接下来去哪：把数据换成远程云原生格式，让"不用先下载文件"成为常态 → 第 2 章。

数据进来：加载云原生格式并转换本地文件

目标：从远程 URL 流式加载 GeoParquet、FlatGeobuf、COG，并把本地数据转成云原生格式。

1. 远程 GeoParquet：打开Add Data → GeoParquet Layer，粘贴 URL 后勾选Stream GeoParquet (no copy)再Load。这个开关让应用通过 HTTP range 请求"原地查询"文件而不整体拷贝进内存，对行按空间排序（如 Hilbert 序）的大文件效果最好——只抓取当前视图相关的 row group。底层逻辑可以看 duckdb-vector-loader.ts 的按需加载实现，读取管线的元数据与坐标系也有专门的测试覆盖（geoparquet-metadata.test.ts、geoparquet-crs.test.ts）。
2. FlatGeobuf：Add Data → FlatGeobuf Layer，输入.fgb地址加载。该格式自带空间索引，GeoLibre 在格式允许时只抓取当前视图内的要素。
3. COG 栅格：Add Data → Raster Layer，输入 COG（.tif）URL 加载，之后在样式面板调亮度、对比度、饱和度、色相。本地 GeoTIFF/COG 也可以直接拖到地图上。
4. 本地转云原生：Processing → GeoLibre Toolbox → Conversion下选工具。其中Vector to GeoParquet、CSV to GeoParquet在浏览器内由 DuckDB-WASM 完成（对应 duckdb-processing.ts 的浏览器内处理管线）；Vector to FlatGeobuf、Vector to PMTiles、Raster to COG走 Python 侧车（桌面端）。
5. 验证：把刚生成的 GeoParquet 重新加回地图，确认渲染正常。

⚠️注意：流式模式对"未排序"的大文件收益有限，此时还是会把文件读进来。想发布大文件，先用转换工具写出 Hilbert 序的 GeoParquet 再分享。

接下来去哪：数据进来了，对它做几何和地形加工 → 第 3 章。

数据加工：矢量分析与地形分析

矢量：缓冲 + 叠加 + 导出

目标：缓冲一个图层，与另一图层叠加，导出结果。

1. 准备输入：至少一个矢量图层；做叠加需要两个，例如点/线图层 + 一个裁剪用多边形图层。
2. 缓冲：Processing → GeoLibre Toolbox → Vector → Buffer，设Input layer、Distance和Units（公里/米/英里），选Engine后Run：
   • Client (Turf.js)：浏览器内跑，零配置，但按地理坐标缓冲；
   • Sidecar (GeoPandas)：Python 侧车跑，投影感知（桌面端）；
   • Python (Pyodide)：浏览器里跑同一套 GeoPandas 代码，结果与侧车一致，运行时首次使用下载一次。
3. 叠加：同菜单下选工具。Clip保留输入中落在叠加点内部的部分（保留属性）；Intersection只留重叠区；Difference减去叠加点区域；Union合并两个多边形（不保留属性）；Spatial join按空间关系把连接图层属性挂到输入要素上；Attribute join按关键字段挂接属性表（一对一，第一个匹配胜出，可选内连接/左连接）。
4. 检查与复跑：在结果图层上开属性表核对输出；Processing → History记录每次运行，可一键重跑并复制等价 Python 代码。

⚠️注意：同一个处理菜单下有两个"Vector"——分隔线上方的Processing → Vector是 Whitebox 目录的矢量类别，本流程用的是Processing → GeoLibre Toolbox → Vector，别点混了。

💡小贴士：大范围要精确的公制距离时，用两个 GeoPandas 引擎之一（缓冲前先重投影）；网页端选Python (Pyodide)即可，不必装侧车。

地形：从 DEM 派生山体阴影、坡度与等高线

目标：一张高程栅格（DEM）进，三个地形产品出。

1. 加载 DEM：以栅格图层方式添加 GeoTIFF/COG 高程数据。栅格工具是"文件进、文件出"，本地或可访问的路径最稳。
2. 山体阴影：Processing → GeoLibre Toolbox → Raster → Hillshade，选 DEM，按需调方位角（azimuth）、高度角（altitude）、z 因子，运行后把浮雕栅格放到其他图层下方，上方图层 混合模式 设Multiply——浮雕能透过颜色显现，而不是像降低不透明度那样把两层一起洗淡。
3. 坡度与坡向：同菜单下的Slope算陡峭程度，Aspect算最陡坡向的罗盘方向。输出用色带（colormap）上色，从控件菜单打开Colorbar显示数值标尺。
4. 等高线：Raster → Contour，选 DEM 并设interval（等高线间距，即线间高差），生成的是矢量图层，可像矢量一样标注和上色。
5. 裁剪到研究区：Clip by extent（边界框，浏览器可跑）或Clip by mask layer（矢量掩膜，仅侧车）。

⚠️注意：Hillshade、Slope、Aspect 都有Client (browser)引擎，在线版零安装可跑；Contour和Clip by mask layer只有侧车引擎，需要桌面应用。每个工具顶部有引擎选择器，大栅格或地理坐标系下的地形建议优先侧车。

接下来去哪：不想一步步点菜单？用 SQL 把同样的分析写成一条查询 → 第 4 章。

结果输出：用 SQL 查询并导出

目标：从Processing → SQL Workspace打开 SQL 工作区（DuckDB-WASM 驱动，浏览器/桌面均可），查完直接上图或导出。

1. 查已加载的图层：每个矢量图层都是一张表。载入国家图层后运行：

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

2. 直接查远程文件：工作区会识别FROM子句里的裸 URL 并自动包上对应读取器，通过 range 请求流式读取，无需先加载（标准 DuckDB CLI 里你得显式写read_parquet('https://...')）。这条能力与 duckdb-vector-loader.ts 同源，防护边界由 duckdb-vector-guard.test.ts 覆盖。

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

3. 用空间函数：空间扩展已加载，ST_*函数全可用。例如算面积并保留geom以便结果上图（EPSG:4326 下ST_Area单位是平方度，要平方千米用ST_Area_Spheroid(geom) / 1e6）。
4. 结果上图：查询返回几何列时点Add as layer，可选命名；结果图层支持识别、选择和属性表，可一次加多个。
5. 导出：Add as layer旁边的Export CSV与Export GeoParquet按钮直接导出查询结果。

💡小贴士：不知道字段名就先跑DESCRIBE SELECT * FROM '你的文件URL'；Sample queries菜单有可运行的示例查询，History可重跑之前的查询。

接下来去哪：分析做完了，把地图变成一个链接或网页组件 → 第 5 章。

发布与嵌入：把地图变成链接和网页组件

目标：拿到一个公开项目链接，并能嵌入任意网页。

1. 配置分享令牌（一次性）：Settings → Environment Variables，把你在 share.geolibre.app 后台"设置 → API 令牌"里创建的令牌粘贴到Share.GeoLibre API token字段。
2. 分享项目：先把地图调到你希望观众落地的视图，然后Project → Share...，确认标题上传。返回一个指向.geolibre.json的公开 URL，形如https://share.geolibre.app/you/my-map.geolibre.json。
3. 打开分享的地图：任何人把项目地址作为url参数传给在线版即可打开，如https://web.geolibre.app/?url=<你的项目地址>。
4. 嵌入网页：用<iframe>+ 嵌入参数控制外壳，参数可组合：

5. 运行时驱动：URL 参数只在加载时生效一次。要持续对话（飞到指定要素、监听图内操作），装类型化客户端npm install @geolibre/embed，实现见 packages/embed/，契约由 embed-api.test.ts 和 embed-client.test.ts 验证。注意：运行时 API 只在把你的页面源加入白名单的自建部署上生效，官方在线版没有开放白名单。

⚠️注意：分享文件只存项目本身（图层、样式、插件状态、视图），绝不上传你的数据文件。读取本地文件的图层会在分享前被对话框列为缺失——这类图层的数据需要你自己找地方托管。

接下来去哪：还有 1000+ 工具和一批进阶玩法值得看 → 第 6 章。

进阶与生态：视频教程、插件与跨端

• 视频教程（收录在 docs/tutorials/videos.md，按时间排列、均带章节和总结）：涵盖 1.0 全功能介绍、浏览器内 Whitebox 地理处理、免费灾害卫星影像、建筑足迹规整、GeoLens 自托管数据栈、Model Builder + AI 助手生成工作流、尼泊尔洪水灾害响应全流程、云原生工作流网络研讨会、影像地理配准等。
• Whitebox 工具箱：1000+ 工具按类别组织（矢量 313、栅格 256、遥感 154、水文 100、地形 99、LiDAR 65、转换 49、网络 26 等），任一工具都可用?tool=URL 参数深链预填表单。
• 插件生态：插件市场提供 Time Slider（栅格序列时间动画）、Vantor Open Data（免费卫星影像）、Atmosphere Effects（深空背景）等，机制见 docs/plugin-api.md。
• 跨端：同一个工作区还有 Android、iOS 原生应用、Chrome 扩展（在任何网页把数据集直接丢进 GeoLibre）、Jupyter 里的 Python 包（python/）与 R 包。想从源码跑，见 docs/getting-started.md。

答疑与选型

常见问题

• 哪些步骤必须桌面端？打开/保存项目文件、读本地 MBTiles 与栅格、侧车工具（等高线、按掩膜裁剪、栅格转 COG 等转换）。Whitebox 工具箱不在其列——浏览器 WASM 就够。
• 缓冲该选哪个引擎？小范围快速预览用Client (Turf.js)；大范围要精确公制距离用Sidecar (GeoPandas)（桌面）或Python (Pyodide)（任意环境）。
• COG 序列怎么动起来？装 Time Slider 插件做时间动画，参考 docs/user-guide/data-integrations.md。
• 嵌入参数能随便组合吗？能，maponly、layout=、toolbar=、panels=、theme=自由叠加。

按场景选起点

• 只想快速出图 → 第 2 章"第一张地图"。
• 面对远程大数据集（Parquet / COG / PMTiles）→ 第 3 章"数据进来"。
• 做几何操作（缓冲、叠加、连接）→ 第 4 章矢量部分。
• 从 DEM 派生地形产品 → 第 4 章地形部分。
• 用 SQL 分析并上图 → 第 5 章。
• 发布与嵌入 → 第 6 章。

收尾

整条主线其实就四件事：数据进来（本地或远程 URL）、数据加工（菜单驱动的几何/地形工具，或一条 SQL）、结果输出（属性表、SQL 导出、转换工具）、发布（分享链接与 iframe 嵌入）。建议先在浏览器里零安装走完一遍，再装桌面端解锁本地文件与侧车工具。想深入某个环节，docs/user-guide/ 下有逐项参考，docs/tutorials/ 保留着官方原版教程可对照练习。

【免费下载链接】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