GeoLibre 中的 USGS NLDI 插件从地图点击到流域水系分析的完整工作流指南【免费下载链接】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/GeoLibreGeoLibre 内置了USGS NLDINational Hydrography Dataset 网络定位与导航插件用于将地图上的任意点回溯到美国国家水文数据集NHD河网中并把流域追踪、上游/下游导航、汇水区basin等结果直接渲染到地图上。本文基于 docs/user-guide/usgs-nldi.md 文档并结合插件源码 maplibre-usgs-nldi.ts 与测试用例 usgs-nldi-plugin.test.ts完整讲解该插件的操作步骤、底层 HTTP 调用链、结果渲染规则、GeoJSON 导出结构与图层集成方式帮助你零门槛上手这套“点一下地图就能做水文网络分析”的工作流。一、插件概览什么是 USGS NLDI 工作流NLDINetwork Linked Data Index是 USGS 提供的公开水文数据服务它把 NHDPlus 河网中的河流线段以COMIDCommon IdentifierNHD 要素唯一编号为索引组织起来并支持沿河网进行上下游导航与站点发现。GeoLibre 的 USGS NLDI 插件围绕这条服务链路封装了三条核心能力点选追踪Flowtrace把地图上点击的坐标映射到最近的 NHD 河段绘制河网流线流域Basin基于追踪得到的 COMID 请求上游汇水区简化多边形导航Navigation沿上游主河道、上游支流、下游主河道、下游分流等方向检索该河段附近的水文要素目录水文站、地下水井、HUC12 汇水点等并叠加绘制。插件调用的是 USGS 公开服务https://api.water.usgs.gov/nldi常量定义见 maplibre-usgs-nldi.ts因此使用前提是网络可达且 USGS 服务允许跨域请求CORS。二、点选追踪把地图点击变成 NHD 河段2.1 操作步骤打开Plugins → USGS NLDI菜单右侧面板随即展开面板通过app.registerRightPanel注册见 maplibre-usgs-nldi.ts。在方向下拉框中选择一种追踪模式Complete flowline完整流线返回包含该点的整条 NHD 河段Upstream only仅上游只返回点击点以上的河段Downstream only仅下游只返回点击点以下的河段。在地图上单击目标位置。面板会显示“Tracing to the nearest NHD flowline…”之类的状态提示对应labels.tracing随后地图上出现渲染结果。2.2 底层调用链nldi-flowtrace 进程点击事件处理器onClickmaplibre-usgs-nldi.ts会先向 NLDI 的pygeoapi 进程端点发起 POST 请求POST https://api.water.usgs.gov/nldi/pygeoapi/processes/nldi-flowtrace/execution?fjson Content-Type: application/json请求体由buildFlowtraceBody(lon, lat, direction)构造是一个符合 OGC API – Processes 规范的 JSON{ inputs: { lat: 38.6, lon: -90.1, direction: none } }其中direction取值none完整、up上游或down下游默认none。这一点在测试用例 usgs-nldi-plugin.test.ts 中有明确断言。parseFlowtraceResponse负责解析响应兼容flowline、flowLine等多种字段拼写并统一把裸 Feature、裸几何对象规范化为 FeatureCollectionmaplibre-usgs-nldi.ts。2.3 降级回退hydrolocation 兜底如果nldi-flowtrace进程因 USGS 服务临时不可用而失败插件不会直接报错而是自动切换到hydrolocation 兜底路径fallbackTracemaplibre-usgs-nldi.ts先调用GET /nldi/linked-data/hydrolocation?fjsoncoordsPOINT(lon lat)把坐标解析到最近的河段再从返回要素中提取 COMID 与“hydrolocation”定位点请求GET /nldi/linked-data/comid/{comid}?fjson取回整条流线用点击坐标与 hydrolocation 定位点构造一条雨滴路径raindropPathLineString 作为兜底渲染。值得注意的是兜底路径不支持方向过滤当用户选择了 Upstream only 或 Downstream only 时若进程离线插件会提示“Directional flowtrace is unavailable…”要求改用 Complete flowline 或稍后重试对应labels.directionalUnavailable。此外即使主流程成功但响应中没有 COMID插件还会再补一次 hydrolocation 请求来尽量补全 COMID以便后续 Basin 与导航按钮可用。2.4 渲染样式规则addLayersmaplibre-usgs-nldi.ts定义了清晰的配色约定要素图层样式NHD 流线flowlineusgs-nldi-flowtrace蓝色实线#1677c8线宽 4雨滴路径raindropPathusgs-nldi-raindrop橙色虚线#f59e0b线宽 3虚线[2, 2]点击点位usgs-nldi-point红色圆点#dc2626半径 6白色描边上游汇水区填充usgs-nldi-basin-fill天蓝#38bdf8透明度 0.18汇水区边界usgs-nldi-basin-line深蓝#0284c7线宽 2导航流线usgs-nldi-navigation-line-{n}紫色#7c3aed线宽 2.5透明度 0.8导航点位usgs-nldi-navigation-point-{n}紫色圆点#7c3aed半径 4白描边每次新的点击都会先清理上一次的点位、流线、雨滴路径与流域图层clearResult导航图层也会被单独清理clearPlottedNavigation避免旧结果混入后续导出或图层集成。三、流域工作流从 COMID 到上游汇水区3.1 触发条件追踪成功并获得 COMID 后面板中的Basin from hydrolocation基于水文定位的流域按钮才会被启用。点击后插件通过lookupBasinmaplibre-usgs-nldi.ts发起请求GET https://api.water.usgs.gov/nldi/linked-data/comid/{comid}/basin?fjsonsimplifiedtruebuildBasinUrlmaplibre-usgs-nldi.ts默认请求simplifiedtrue简化几何以降低渲染与存储开销测试用例 usgs-nldi-plugin.test.ts 验证了默认值及可显式关闭简化的行为。响应被渲染为天蓝半透明填充多边形 深蓝边线状态栏提示“Upstream basin rendered for COMID {comid}”。3.2 并发安全请求代际管理由于 Basin 与导航请求共享同一个“请求令牌”插件使用requestId代际计数generation与AbortController实现严格并发控制beginRequest、isCurrent见 maplibre-usgs-nldi.ts任何较新的点击、Basin 或导航请求都会中止并作废仍在途的旧请求防止过期响应覆盖新结果。所有 HTTP 请求统一走fetchJson封装maplibre-usgs-nldi.ts带30 秒超时REQUEST_TIMEOUT_MS 30_000并把 NLDI 的错误响应体linked-data 端点用description、pygeoapi 进程用detail解析为可读的 HTTP 错误提示。四、导航工作流沿河网发现水文要素4.1 操作流程追踪成功后面板提供四个导航方向Upstream main上游主河道沿主干河道向上游延伸Upstream tributaries上游支流沿上游支流分支Downstream main下游主河道沿主干河道向下游延伸Downstream diversions下游分流沿分流路径。完整步骤为在Distance距离单位 km输入框中设定搜索半径合法范围为19999 km默认值500源码 maplibre-usgs-nldi.ts超出范围会提示invalidDistance点击1. Load sources plot navigation加载目录并绘制导航插件先请求导航链接列表再拉取可用的要素目录从catalog 下拉框中选择一个数据源再次点击按钮此时变为Plot another navigation layer绘制另一导航图层即可把该目录的要素绘制到地图上。4.2 底层调用链两步式导航请求plotNavigationmaplibre-usgs-nldi.ts先把流程拆成两个阶段第一步——获取导航链接与目录GET https://api.water.usgs.gov/nldi/linked-data/comid/{comid}/navigation?fjson响应中按方向给出导航 URL例如upstreamMain、upstreamTributaries等键buildNavigationUrlmaplibre-usgs-nldi.ts。随后插件对所选方向的 URL 发起带distance参数的请求并用parseNavigationSourcesmaplibre-usgs-nldi.ts递归遍历响应中的source/features键值对解析出可绘制的数据目录清单。第二步——拉取所选目录的实际要素GET {navigationSourceUrl}?fjsondistance{km}buildNavigationSourceUrlmaplibre-usgs-nldi.ts保留原 URL 自带的fjson参数并追加distance它还支持trimStart、stopComid、trimTolerance等可选参数测试用例 usgs-nldi-plugin.test.ts 逐一验证默认distance500。目录清单会被缓存缓存键为“方向|距离”因为搜索半径会影响目录范围更换导航方向会清空目录列表并复位按钮文案。4.3 可用的 NLDI 数据目录插件默认提供了下列目录的显示名称映射catalogNamesmaplibre-usgs-nldi.ts实际可用列表以 NLDI 服务对当前 COMID 的返回为准目录标识含义flowlinesNHDPlus 流线默认选中并排在最前nwissiteNWIS 地表水站点水文站 / streamgagesca_gages加利福尼亚州水文站nwisgwNWIS 地下水井gfv11_poisUSGS Geospatial Fabric 点huc12ppHUC12 汇水点pour pointsnmwdi-st新墨西哥州水体站点4.4 导航图层的渲染与交互导航结果由addNavigationLayermaplibre-usgs-nldi.ts渲染按几何类型拆分线要素绘制为紫色折线点要素绘制为紫色圆点每一层导航对应一组独立图层usgs-nldi-navigation-line-{n}/usgs-nldi-navigation-point-{n}。插件还为这些图层挂接了hover 悬停弹窗鼠标移入要素时显示指针光标并弹出该要素的前 8 个非空属性popupText跳过_开头的内部字段。若响应中没有可绘制的点/线几何插件会明确提示“该目录未返回可绘制要素”而不是无声地跳过。多次点击“Plot another navigation layer”可以叠加多个导航图层已绘制的图层不会被新的导航请求清除“Existing navigation layers remain on the map.”。五、结果输出GeoJSON 导出与图层集成5.1 导出为 GeoJSON点击Export rendered results to GeoJSON会调用app.exportTextFile把当前全部结果打包成一个 FeatureCollection默认文件名为nldi-{comid}.geojson无 COMID 时为nldi-result.geojson。导出内容包含见 maplibre-usgs-nldi.tsflowlineNHD 流线raindropPath雨滴路径selectedPoint点击点位属性中携带comidbasin上游汇水区如已请求navigation-1、navigation-2…每次绘制的导航结果。exportCollection通过addLayerTag为每个要素写入_nldiLayer属性来标识它所属的结果分组maplibre-usgs-nldi.ts。因此导出文件可以用feature.properties._nldiLayer精确区分流线、雨滴路径、点位、流域与各导航图层便于后续程序化处理。5.2 集成进 GeoLibre Layers 面板点击Add rendered results to GeoLibre Layers会把当前所有已渲染结果复制到图层面板插件在 GeoLibre 图层树中创建一个“USGS NLDI results”分组其中依次包含NLDI flowline流线NLDI raindrop path雨滴路径NLDI selected point选中点NLDI upstream basin上游流域如已生成NLDI navigation 1 / 2 / 3…已绘制的导航图层实现上使用app.addGeoJsonLayer逐层加入再用app.addLayerGroup建组若分组已存在则复用并通过app.moveLayersToGroup追加maplibre-usgs-nldi.ts。插件内部通过addedParts集合记录已加入的要素分组避免重复点击时把同一批结果复制两次。这些复制进图层面板的图层会随项目持久保存即使地图上的临时 NLDI 覆盖层被清理图层数据依然保留。点击Clear NLDI result则中止进行中的请求并清空地图上的所有临时覆盖层不影响已加入图层面板的内容。六、源码实现细节与工程保障6.1 插件架构与国际化插件实现为一个符合 GeoLibre 插件协议的GeoLibrePluginid: maplibre-usgs-nldi注册于 packages/plugins/src/index.ts。由于packages/plugins是框架无关包无法直接使用 react-i18next插件的全部文案通过UsgsNldiLabels接口与默认标签集DEFAULT_USGS_NLDI_LABELS管理再由桌面端应用通过setUsgsNldiLabels推送翻译TopToolbar.tsx中把usgsNldi.*的 i18n 词条逐项映射进标签对象TopToolbar.tsxapplyLabels回调会在语言切换时实时重刷面板文案。中、英、法、日等多语言词条可在 locales/zh.json 等目录中找到usgsNldi键。6.2 URL 构造与解析的正确性保障插件把 URL 构造与响应解析抽成纯函数buildHydrolocationUrl、buildBasinUrl、buildNavigationUrl、buildNavigationSourceUrl、buildFlowtraceBody、parseFlowtraceResponse由 tests/usgs-nldi-plugin.test.ts 系统性地验证点击坐标编码为 WKTPOINT(lon lat)且请求fjsonbasin 请求默认simplifiedtrue对含路径分隔符的目录标识与 COMID 做百分号编码%2F、%3F导航 URL 追加参数时保留原有查询串direction默认值与up分支的请求体构造响应解析对裸 FeatureCollection、裸 Feature、裸几何、大小写 COMID、垃圾输入null / 数字 / 字符串的健壮性。这些测试保证了插件面对 USGS 服务多变的响应格式时能稳定工作也印证了本文所述调用链的真实性。七、使用前提与限制网络与 CORS插件依赖公开的https://api.water.usgs.gov/nldi需要网络可达且 USGS 服务的 CORS 策略允许浏览器跨域调用文档明确说明“network access and the service’s CORS policy are required”。方向追踪的可用性Upstream / Downstream 方向追踪依赖nldi-flowtrace进程在线进程离线时自动降级为 hydrolocation 完整流线仅 Complete flowline 可用并给出明确提示。服务端数据决定论可用的导航目录清单、COMID 是否存在、basin 是否可求均由 NLDI 服务对当前河段的返回决定插件不保证每个点都能命中河网对应noFlowlineNearby、navigationUnavailable等提示。距离参数导航距离仅接受 19999 km 的整数步长 1。八、典型工作流速查打开 Plugins → USGS NLDI → 选择方向Complete / Upstream / Downstream → 单击地图触发 nldi-flowtrace必要时 hydrolocation 兜底 → 地图渲染蓝流线 橙雨滴路径 红点位 → [可选] Basin from hydrolocation简化上游汇水区天蓝填充 → [可选] 选导航方向 → 设距离km→ 1. Load sources plot navigation → 选目录flowlines / nwissite / ca_gages / nwisgw / gfv11_pois / huc12pp / nmwdi-st … → Plot another navigation layer紫线/紫点叠加可多次 → [可选] Export rendered results to GeoJSONnldi-{comid}.geojson含 _nldiLayer 分组标记 → [可选] Add rendered results to GeoLibre Layers并入 “USGS NLDI results” 图层组随项目保存 → Clear NLDI result 清理临时覆盖层以上完整工作流把“地图上一个普通的点击”串联为“COMID → 流域 → 水文要素目录 → 可持久化图层”的一体化水文分析管线。若要深入插件实现细节渲染、并发控制、导出逻辑可直接阅读 maplibre-usgs-nldi.ts若需验证各 URL 构造与响应解析行为可参考 usgs-nldi-plugin.test.ts。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
