示例数据

在线沙箱与 SDK 示例里的服务（demo/roads、demo/basemap 等）是逻辑名，由一份服务映射对应到平台上的实际服务。本页说明示例用到哪些数据、从哪里获取，以及如何用发布脚本把它们发布到自己的平台，供搭建演示环境的操作者参考。

数据集

二维示例统一使用香港的 OpenStreetMap 数据：范围紧凑、要素丰富，切换示例时视野一致。三维示例的数据见文末「三维示例数据」一节。

来源：Geofabrik 提供的 OpenStreetMap 区域提取，香港 Shapefile 免费版，下载地址 https://download.geofabrik.de/asia/china/hong-kong.html（文件名形如 hong-kong-latest-free.shp.zip，坐标系 WGS84）。
授权：开放数据库许可（ODbL 1.0）。使用时须署名「© OpenStreetMap 贡献者」；对数据库本身的修改与衍生数据库须按相同许可共享。发布脚本会把署名写进每个服务，地图方案的样式里也带有署名。

逻辑名	数据（Shapefile 图层）	服务能力	访问级别	示例中的用途
`demo/roads`	道路 `gis_osm_roads_free_1`	地图服务、要素服务、矢量瓦片、WMS、OGC API	公开	矢量瓦片样式、按道路等级配色、属性查询、OGC API Features 与矢量瓦片
`demo/pois`	兴趣点 `gis_osm_pois_free_1`	地图服务、要素服务、矢量瓦片	公开	热力图、类别筛选、聚合、地名搜索、统计
`demo/buildings`	建筑 `gis_osm_buildings_a_free_1`	矢量瓦片	公开	悬停高亮
`demo/landuse`	土地利用 `gis_osm_landuse_a_free_1`	地图服务、要素服务、矢量瓦片、WMS、WFS	公开	识别、WMS 叠加、专题图
`demo/water`	水体 `gis_osm_water_a_free_1`	地图服务、矢量瓦片	公开	底图组成
`demo/protected`	交通设施 `gis_osm_transport_free_1`	要素服务、矢量瓦片	API Key	API Key 示例
`demo/basemap`	地图：土地利用 + 水体 + 道路	地图服务（切片）、WMTS、TMS、OGC API	公开	栅格底图、WMTS（MapLibre、OpenLayers、Cesium）、TMS、OGC API 地图瓦片、切换底图
`demo/map`	地图方案：以上矢量瓦片组成的浅色香港底图	公开样式地址	公开	地图方案样式

说明：

矢量瓦片里的图层名（MapLibre 样式中的 source-layer）与服务名相同，例如 hk_roads。
道路的等级在 fclass 字段（motorway、primary、residential、footway 等），土地利用、兴趣点、水体同样用 fclass 区分类别，名称在 name 字段。
免费提取没有建筑高度字段，示例不做建筑拉伸；也没有海域面，地图方案里的海面与没有土地利用覆盖的陆地同为底色。

准备数据

脚本不联网下载，数据需要自行下载并核对授权。

下载并解压香港 Shapefile 免费版。

把下面每个图层的 .shp、.shx、.dbf、.prj、.cpg 五个文件各打成一个 zip，放进同一个目录（zip 内不要再套目录）：

zip 文件名	图层
`roads.zip`	`gis_osm_roads_free_1`
`pois.zip`	`gis_osm_pois_free_1`
`buildings.zip`	`gis_osm_buildings_a_free_1`
`landuse.zip`	`gis_osm_landuse_a_free_1`
`water.zip`	`gis_osm_water_a_free_1`
`transport.zip`	`gis_osm_transport_free_1`

例如：zip -j roads.zip gis_osm_roads_free_1.{shp,shx,dbf,prj,cpg}。

运行发布脚本

发布脚本是仓库中的 scripts/demo-data/publish-demo.mjs（Node.js 24，无需安装依赖）。它按清单依次完成：上传数据、创建数据源与图层（土地利用、水体、道路同时配上 SLD 样式）、发布服务、启动、设访问级别；再把土地利用、水体、道路组成地图并发布为带切片与 WMTS 的地图服务；最后用样式模板创建地图方案、保存版本并设为公开。全部成功后输出服务映射。

在控制台登录要发布到的工作空间所属账号（需要该工作空间的写与管理权限），从浏览器开发者工具的 Cookie 中复制名为 geobridge-token 的值。
把它读进环境变量（用 read -s，令牌不会显示，也不会写进 shell 历史）：
bash
```
read -s GEOBRIDGE_SESSION_TOKEN && export GEOBRIDGE_SESSION_TOKEN
```

运行（工作空间 id 在控制台工作空间详情页的地址中）：

bash

node scripts/demo-data/publish-demo.mjs \
  --data <数据目录> \
  --base-url https://map-demo.geobridge.cn/geobridge-mapserver \
  --workspace <工作空间 id> \
  --out frontend/apps/sandbox/examples/demo-services.site.json

参数：

参数	说明
`--data`	放 zip 文件的目录
`--base-url`	平台地址，含上下文路径
`--workspace`	发布到的工作空间 id
`--out`	映射输出文件，可写多次输出多份；不写时打印到标准输出
`--manifest`	清单文件，缺省为脚本同目录的 `demo-manifest.json`
`--map 逻辑名=方案 id`	直接使用已有的地图方案，不再创建（可写多次）
`--reuse`	已存在同名服务（或同名地图方案）时沿用它：服务须在运行中，方案须已有发布版本；不加时遇到同名即报错中止。沿用的服务同样会补上或更新清单中的样式（见下文「图层样式」）

行为与安全：

令牌只从环境变量 GEOBRIDGE_SESSION_TOKEN 读取，不接受命令行参数；进度日志与错误消息都不含令牌。
服务先按「私有」创建，发布并启动后再改为清单中的访问级别，并回读核对。
发布某个服务失败时，脚本删除这次新建的服务（地图服务连同新建的地图一起删除）；地图方案在保存版本、设级别或公开前检查中失败时同样删除新建的方案。已上传的数据源与图层保留，可在控制台清理。
任何一步失败都不写映射文件，退出码为 1。中途失败后修正问题，加 --reuse 重跑即可跳过已经发布好的服务。

图层样式

demo/basemap（hk_basemap）是服务端出图的栅格底图，出图效果由图层的 SLD 样式决定。清单为土地利用、水体、道路三个 layer 条目配了浅色样式，配色与地图方案 demo/map 一致：

文件	内容
`scripts/demo-data/styles/hk_water.sld`	水面浅蓝 `#aad3ee`，湿地浅青
`scripts/demo-data/styles/hk_landuse.sld`	按 `fclass` 分类的淡色填充（林地、公园绿地、农用地、住宅、商业、工业、墓地、军事），其余类别一个缺省淡色
`scripts/demo-data/styles/hk_roads.sld`	按 `fclass` 分级、按比例尺分档的线宽：高速与快速路黄色带深色外框，主干道浅黄，次干道与支路白色带灰框，步道 16 级起显示为虚线，隧道为半透明虚线；先画全部外框再画全部内线。规则 `Name` 带档位（如"次干道外框 14 级"），`Title` 只写等级（外框与内线相同，如"次干道"），所以 WMS 图例每个等级一行、外框与内线叠画

清单写法：

layer 条目可写 "style": "styles/hk_roads.sld"（相对清单所在目录），脚本把它存为工作空间样式库中与服务同名的样式，图层与图层服务都引用它。
map 条目里的图层默认沿用各自 layer 条目的样式；需要为某张地图单独配样式时写 "styles": { "demo/roads": "styles/xxx.sld" }，存为名为「地图服务名-图层名」的样式。

样式按名称在工作空间内查找：没有就创建，SLD 不同就更新。服务配置中的图层以 style:<样式 id> 引用样式（出图只看这里，图层记录上的样式只用于控制台显示与以后重新发布）。加 --reuse 重跑时，脚本对已存在的服务依次：更新样式库中的样式、设图层的样式、改写服务配置里的样式引用（整行写回后等服务重新就绪）、对地图服务同步地图记录里的样式；样式内容或引用有变化时再调用 POST /api/services/{id}/tile-cache/purge 清除该服务的瓦片缓存。因此修改 SLD 后只需加 --reuse 重跑脚本，香港底图、hk_roads 与 hk_landuse 的地图服务与 WMS 会一起更新。

道路数据有十几万条，按整层要素数估算，平台的自动降级会在 11 级及更小比例尺下省略整个道路图层。hk_roads.sld 在小比例尺只画高速、快速路、主干道（10–11 级再加次干道），规则带 fclass 过滤与比例尺范围，自动降级按生效规则估算（10–11 级约 2.3 万条、9 级及以下约 1.4 万条），因此全港视野的底图仍有道路；hk_roads 与香港底图的 MapServer JSON（minScale）、WMS 能力文档（MaxScaleDenominator）同样按此报告（服务就绪后统计完成即报 0，不限），ArcGIS JS 等按最小比例尺隐藏图层的客户端在小比例尺下也会请求道路。若改用不带过滤的样式，11 级及以下仍整层省略（响应头 X-GeoBridge-Omitted-Layers）。

输出的映射形如：

json

{
  "services": {
    "demo/roads": "hk_roads",
    "demo/basemap": "hk_basemap",
    "demo/protected": "hk_transport"
  },
  "maps": {
    "demo/map": "<地图方案 id>"
  }
}

发布之后

demo/protected 是 API Key 级别：在该工作空间的「API Key」页签创建一个不限制来源域名的 Key（沙箱运行页的来源不固定），填进沙箱顶部的 API Key 输入框即可运行 Key 示例。其余服务与地图方案是公开的，不填 Key 也能运行。
可以用下面的地址自查（把 <Key> 换成刚创建的 gb_xxx…）：
- https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/hk_roads/VectorTileServer/tiles.json：公开服务，匿名返回 200。
- https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/hk_transport/VectorTileServer/tiles.json：匿名返回 401，加 ?token=<Key> 返回 200。
- https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/maps/<地图方案 id>/style.json：地图方案的公开样式。
地图方案的样式模板是脚本同目录的 demo-map-style.json，其中用双花括号括起的 BASE_URL 与 service:逻辑名 两种占位符，由脚本分别替换为平台地址与服务路径。方案创建后也可以在地图编辑器里继续修改并保存新版本。

三维示例数据（实验功能）

三维仍是实验功能，平台需开启 GEOBRIDGE_FEATURE_3D=true 才能发布与预览下列服务。清单 demo-manifest.json 末尾的六个 kind: "3d" 条目覆盖栅格地形、网格地形、三维模型、高斯泼溅、3D Tiles 与点云，访问级别都是公开，沙箱与文档可匿名使用。

示例数据以在线系统实际提供为准。 网格地形与高斯泼溅两项没有可以公开分发的推荐数据，在线系统未必提供；搭建自己的演示环境时，请换成来源与许可明确的数据并同步修改清单。

数据与许可

逻辑名	服务名 / 类型	数据	许可与署名
`demo/terrain-raster`	`hk_terrain_dem` / 栅格地形（RasterTerrainServer，Terrarium 编码，按图层动态生成）	Copernicus DEM GLO-30 N22E114（香港，COG，约 24 MB）	Copernicus DEM 许可，允许商用，须署名「© DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA」（已写进服务署名）
`demo/terrain-mesh`	`gz_terrain_mesh` / 网格地形（MeshTerrainServer）	量化网格地形（quantized-mesh-1.0，`layer.json` + `.terrain`），服务器目录	须使用来源与许可明确的地形数据（例如用 Copernicus DEM 自行生成的量化网格）；演示环境自备的地形不对外提供
`demo/models`	`hk_models` / 三维模型（3DModelServer）	Khronos glTF 样例 `Duck.glb`、`DamagedHelmet.glb`、`CesiumMilkTruck.glb`，放在尖沙咀海滨	Duck：© 2006 Sony，SCEA Shared Source License 1.0；DamagedHelmet：重建与转换 © 2018 ctxwing（CC BY 4.0），所依据的原作 © 2016 theblueturtle_（CC BY-NC 4.0，非商业）；CesiumMilkTruck：© 2017 Cesium（CC BY 4.0，Cesium 标志为商标）。各模型以 glTF-Sample-Assets 仓库中的 `metadata.json` / LICENSE 为准
`demo/splat`	`hk_splats` / 三维模型（3DModelServer，发布后转为高斯泼溅 3D Tiles）	高斯泼溅样例两份（`.splat` 与 `.spz` 各一），放在西九文化区	须使用来源与许可明确的泼溅数据；演示环境自备的样例来源许可未声明，不对外提供
`demo/tiles3d`	`hk_pland_3dtiles` / 3D Tiles（Cesium3DTileServer）	香港规划署三维实景 3D Tiles `tile_22_26`（金钟一带，b3dm，解压后约 313 MB），服务器目录	DATA.GOV.HK 使用条款：可免费使用（含商用），须注明来源，数据「仅供参考」；服务署名「© 香港特别行政区政府规划署（DATA.GOV.HK）」
`demo/pointcloud`	`autzen_pointcloud` / 3D Tiles 点云（Cesium3DTileServer，发布后由 LAZ 转为 pnts）	PDAL 样例 Autzen 已分类 COPC（`autzen-classified.copc.laz`，1065 万点，带 RGB、强度、分类，约 77 MB）	PDAL 公开样例数据（Watershed Sciences / DOGAMI）

说明：

模型与泼溅的位置来自清单的 placements（逐文件默认位置：经纬度、高度、朝向、缩放），三个模型约 60 米间隔、缩放到 15–30 米大小，两个泼溅约 60 米间隔；修改默认位置不需要重新转换泼溅（tileset 的根变换在读取时按默认位置生成）。
每个条目都带 initialView（Cesium 风格的经纬度、高度与 heading / pitch / roll，pitch −90 为俯视），作为服务的初始视角。栅格地形在控制台以 MapLibre 预览，打开左下角「三维地形」开关才有起伏。
缩略图需要渲染画面，脚本不生成：发布后在控制台打开服务预览，调整好画面后点「设为缩略图」。
3D Tiles 数据的 tileset.json 为较早的写法（asset.version 0.0、content.url、小写 refine），Cesium 能正常加载，只在控制台输出弃用警告。

准备数据

样例数据目录（下称三维数据目录）中按下列相对路径放好文件，脚本只读取、不修改：

相对路径	用于
`03-terrain/S/copdem30/Copernicus_DSM_COG_10_N22_00_E114_00_DEM.tif`	`demo/terrain-raster`（上传）
`04-3d-models/S/gltf/{Duck,DamagedHelmet,CesiumMilkTruck}.glb`	`demo/models`（脚本打成 `hk_models.zip` 上传）
清单 `demo/splat` 条目 `files` 中列出的泼溅文件（换成你有权使用的数据时同步修改清单）	`demo/splat`（打成 `hk_splats.zip` 上传）
`07-pointcloud/M/copc/autzen-classified.copc.laz`	`demo/pointcloud`（上传）

网格地形与 3D Tiles 体积大，走服务器目录数据源（不上传）：平台需配置服务器数据根目录 GEOBRIDGE_SERVER_DATA_ROOTS，清单按根目录名 geodata 引用：
- geodata:terrain/terrain：量化网格目录（含 layer.json）；
- geodata:demo3d/hk-pland-tile_22_26：把 08-3dtiles/M/hk-pland/tile_22_26_CESIUM.zip 解压到数据根目录的 demo3d/hk-pland-tile_22_26/ 下（解压后目录里是 tileset.json 与 Data/）。
服务器目录只适合本机或内网演示环境；在线系统不要配置 GEOBRIDGE_SERVER_DATA_ROOTS，此时把这两个条目改为 file / files 上传（3D Tiles 可直接上传 zip，大于 100 MB 时脚本分片上传）。

运行

在二维的命令上加 --data3d <三维数据目录>；三维条目在二维条目之后发布，映射文件一并输出。已发布的二维服务与地图方案可加 --reuse 与 --map demo/map=<方案 id> 沿用：

bash

node scripts/demo-data/publish-demo.mjs \
  --data <二维数据目录> --data3d <三维数据目录> \
  --base-url <平台地址> --workspace <工作空间 id> \
  --reuse --map demo/map=<方案 id> \
  --out frontend/apps/sandbox/examples/demo-services.json \
  --out frontend/apps/sandbox/examples/demo-services.site.json

每个三维条目依次：建数据源（上传或服务器目录）并准备数据 → 按数据源类型发现数据（shapefile-layers?tileType=…；栅格地形走 GeoTIFF 发现）→ 建图层 → 建服务（先私有）→ 发布、启动、设访问级别与署名 → 设模型默认位置 → 等待转换完成 → 设初始视角。点云与泼溅发布后由平台转换为 3D Tiles，脚本轮询服务目录详情（点云看 …/Cesium3DTileServer?f=json 的 pointCloud.status，泼溅看 …/3DModelServer?f=json 各泼溅文件的 tilesStatus），全部 ready 才算完成；连续几次仍未提交时调用一次「重新生成」，转换失败或超过 60 分钟报错（加 --reuse 重跑时，上次失败的会自动重新生成一次）。本机实测：两份泼溅约 1 分钟，Autzen 点云约 1 分钟。

加 --reuse 重跑时，已存在且运行中的二维服务若缺少清单中的能力（如后来加的 TMS、OGC API），脚本把缺的能力补进服务的能力串（只增不减），无需重新发布。沿用已存在且运行中的三维服务，只补齐与清单不一致的默认位置和初始视角，已转换好的不会重复转换。

清单写法

三维条目的字段（kind 为 "3d"，其余同二维条目的 logical、serviceName、title、description、accessLevel、attribution）：

字段	说明
`datastoreType`	`tiff`（栅格地形）、`meshterrain`（网格地形）、`3dtiles`、`3d-model`（模型与泼溅）、`point-cloud`（LAS / LAZ），决定服务类型
`file` / `files` / `serverPath`	三选一：`file` 为三维数据目录下的单个文件；`files` 为多个文件，脚本打成 `<服务名>.zip` 上传；`serverPath` 写成 `根目录名:相对路径`，引用服务器目录
`nativeName`	数据源里有多份数据时选哪一份（如模型 zip 中的 `Duck.glb`，模型服务仍会列出 zip 中的全部模型）
`datastoreParams`	数据源的附加参数，如模型的 `format`、点云的 `format: "laz"`
`placements`	仅 `3d-model`：文件名 → `{ lng, lat, alt, heading, pitch, roll, scale }`，`alt` 等缺省为 0、`scale` 缺省为 1
`initialView`	`{ longitude, latitude, height, heading, pitch, roll }`
`terrain`	仅栅格地形：`{ encoding: "terrarium" \| "mapbox", maxzoom }`，`maxzoom` 不写时由平台按分辨率推算
`tiles`	是否等待转换：缺省按数据推断（点云为 `pointcloud`，含 .ply / .splat / .spz 的模型为 `splat`），写 `none` 不等待

示例数据 ​

数据集 ​

准备数据 ​

运行发布脚本 ​

图层样式 ​

发布之后 ​

三维示例数据（实验功能） ​

数据与许可 ​

准备数据 ​

运行 ​

清单写法 ​

示例数据

数据集

准备数据

运行发布脚本

图层样式

发布之后

三维示例数据（实验功能）

数据与许可

准备数据

运行

清单写法