/dem2terrain

根据dem数据生成地形切片的工具

Primary LanguageJavaScriptBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

简介

根据 DEM 数据生成地形切片工具,使用 NodeJS + GDAL(NodeBinding)开发制作。可用于用户自定义 DEM 高程数据源生产地形瓦片,以便局域网离线使用。

特点:

  • 支持 mapboxterrarium 两种地形瓦片编码格式供mapboxgl使用,其中terrarium格式是tangram引擎的官方地形格式,tangram是另外一款开源的webgl二三维一体化的引擎;
  • 固定瓦片尺寸256,瓦片周围有1cell的buffer,即实际瓦片是258*258.
  • 自动读取数据源的坐标系统,重编码输入的 DEM 栅格文件,并重投影至指定的坐标系4490、4326、3857,默认3857,然后生成瓦片;
  • 支持适用于3857、4490、4326的地形切片生产;
  • 内置了影像金字塔索引和多进程实现(暂未使用多线程),加速瓦片生成速度;
  • 支持地形瓦片以文件目录或mbtiles两种格式存储;
  • 命令行提供了瓦片生成的进图条提示,便于用户查看生成进度。
  • 内置一些异常导致的临时文件清理工作。

生成进度条

1. 安装与配置

1.1. 配置 GDAL_DATA

由于使用了 GDAL,用户需要 下载 gdal-data.zip 数据包,并配置 GDAL_DATA 环境变量为解压缩的目录。

以 Windows 操作系统为例(此例直接使用 PostgreSQL 附带的资源,若用户有安装 PostgreSQL,也可以直接使用对应目录):

配置环境变量

1.2. 安装

从网络全局安装,成为命令行工具:

npm i dem2terrain -g
yarn add dem2terrain -g
pnpm add dem2terrain -g

源码安装(先将当前目录定位至工程根目录,且明白什么是 link 命令):

npm install && npm link
#
yarn && yarn link
#
pnpm install && pnpm link --global

安装完毕后就可以当普通命令行程序使用了。

1.3. 测试

测试地形数据生产:

npm run test

基于maplibregl地形预览:

npm run server

浏览器输入地址进行预览:http://[ip]:[port]/terrain.html

效果图如下:

地形测试可视化

2. 用法与说明

当前支持作为命令行使用:

> dem2terrain --help
Usage: dem2terrain [options]

使用 GDAL 制作地形瓦片,支持 mapbox 和 terrarium 两种编码输出格式,当前仅输出 PNG 容器格式。

Options:
  -v, --version               当前版本
  -i, --input <string>        <必填> 输入 tif 格式的 DEM 文件路径,支持相对路径
  -o, --output <string>       <必填> 输出目录,支持相对路径
  -f, --configFile <File>     <可选> 通过配置文件执行任务,输入绝对路径,可参考配置模板
  -g, --epsg <number>         <可选> Tile适用坐标系,3857 | 4490 | 4326 (default: 3857)
  -r, --resampling <number>,  <可选> 构建影像金字塔或重投影时设置重采样策略,默认3,1:AVERAGE|2:BILINEAR|3:CUBIC|4:CUBICSPLINE|5:LANCZOS|6:MODE|7:NEAREST
  -c, --clean <number>        <可选> 是否清空输出目录,0 | 1 (default: 0)
  -z, --zoom <number-number>  <可选> 指定瓦片的等级生成范围。例如,想生成 7 ~ 12 级的瓦片,则输入 -z 7-12 (default: "5-14")
  -e, --encoding <string>     <可选> 指定瓦片的数据编码规则(mapbox 或 terrarium) (default: "mapbox")
  -h, --help                  帮助

可选参数说明:

  • -i: 输入 tif 格式的 DEM 文件路径,支持相对路径;
  • -o: 输出目录,支持相对路径;
  • -g: 指定地形Tile适用坐标系,默认是适用3857坐标系;
  • -r: 构建影像金字塔或重投影时设置重采样策略,默认3 CUBIC 采样;
  • -z: 由于地形栅格数据通常是 90m、30m 的空间分辨率,等级太大意义不大,等级太低时起伏辨识也不高,所以默认生成中间的 5-14 级;
  • -c: 指定是否预先清理输出瓦片的存储目录,默认0,不清理;
  • -e: 指定切片编码规则,默认 mapbox,用户可指定 terrarium 规则输出。
  • -f: 以上参数可以都放到一个配置json文件里,使用-f执行切片任务,简化操作;

2.1 任务执行

有两种形式执行命令行任务

  • 方式1:通过命令行参数执行任务
dem2terrain -z 4-15 -e terrarium -i ./ZONE.tiff -o ./output -c 1 -g 3857
  • 方式2:通过配置文件执行任务

1)配置参数

{
    "zoom":"5-13",
    "epsg": 3857,
    "encoding": "mapbox",
    "input": "./data/xxx.tif",
    "output": "./data/tile",
    "clean": true
}

2)执行任务

dem2terrain -f d://config.json

2.2 数据输出

支持地形切片生成以文件或mbtiles目录两种形式存储。

  • 以文件存储

-o参数为文件目录,则以文件形式存储:

dem2terrain -z 4-15 -e terrarium -i ./ZONE.tiff -o ./output -c 1 -g 3857
  • 以mbtiles存储

-o参数带.mbtiles扩展名,则以mbtiles形式存储:

dem2terrain -z 4-15 -e terrarium -i ./ZONE.tiff -o ./output/tile.mbtiles -c 1 -g 3857

3. 使用输出成果

使用 HTTP(S) 协议的 Web 服务器(例如 nginxIIS)将生成的地形瓦片作为静态资源发布,即可使用。

举例:根据 MapboxGL 地形示例 简单修改,将在线数据源换成本地 Web 服务器发布的地址即可,注意编码格式要与生成时输入的编码格式一致。

// 数据编码,'mapbox'或'terrarium'
const encoding = 'mapbox';
const maxZoom = 14;
map.addSource('my-custom-terrain', {
  type: 'raster-dem',
  encoding:encoding,
  // 使用tiles方式替换本地发布的地形切片服务
  tiles: ['./mapbox/{z}/{x}/{y}.png'],
  // 注释掉官方的服务url,替换自己的
	//'url': 'mapbox://mapbox.mapbox-terrain-dem-v1',
  tileSize: 256,
  maxzoom: maxZoom,
})

如下图所示:

本地离线切片可视化

4. TODO

当前版本足够 MapboxGL.js 使用,但仍然有新功能未开发,留待以后扩展功能,初步拟定待扩展功能如下:

  • 大数据量的dem tif改用分块读取分块处理
  • 扩展 gdal 驱动,使其支持 webp,直接生成 webp 格式的切片
  • 重构核心模块,解耦,扩展使其支持生成 CesiumJS 支持的地形切片格式

欢迎参与贡献,包括但不限于文档、功能扩展、性能优化!

5. 安装问题

5.1 c++编译环境问题

由于node-gdal、node-gdal-next或node-gdal-async都会内置编译安装一个gdal,编译是需要依赖c++环境的,在win上常出现问题如下:

npm ERR! gyp ERR! stack Error: Could not find any Visual Studio installation to use

如果用户未安装vs c++环境,请最好安装下vs c++编译环境。 如果用户已经安装了vs,例如vs2022仍提示找不到,配置如下:

# 配置npm的msvs版本号,例如安装了vs 2022
npm config set msvs_version 2022
# 更新下node-gyp
npm install node-gyp@latest -g

5.2 环境变量冲突

在node-gdal系列相关包npm安装成功后,使用过程中遇到投影操作定义就会报各种错误,典型错误如下:

const srs= gdal.SpatialReference.fromProj4('+init=epsg:4326'); ^ Error: Corrupt Data

主要原因是win上各种软件包都会内置安装,环境变量冲突导致。

例如,用户安装了PostGIS,会内置安装proj,geos,gdal并自动生成proj_lib的环境变量。

PROJ_LIB=C:\Program Files\PostgreSQL\14\share\contrib\postgis-3.1\proj

当安装node-gdal-next或noe-gdal-async时,内置的proj和proj.db由于冲突不能生效,就会在使用过程中报各种错误。 依此类推,如果用户安装了独立的GDAL,又有内置的proj,geos和环境变量也会有这种问题。 解决办法:从系统环境变量中删除这些冲突的环境变量重启机器即可。

5.3 最好的办法

使用本机已编译好的gdal编译binding下node的gdal环境:

npm install gdal-next --build-from-source --shared_gdal

npm install gdal-async --build-from-source --shared_gdal

这样,node的gdal环境可以和本机的gdal环境一致,能使用更多的驱动例如webp,内置驱动是没有的。 这种操作可以让公用软件装一次,不会产生更多的冲突,linux上很方便。但由于windows上都不是源码编译,从.exe安装,因此不太适用。该操作适合c++编译环境熟悉的高级用户可定制安装多项扩展。

6. 知识补充

6.1. 参考资料

6.2. 编解码差异

mapboxterrarium 都将高程值编码成 RGB 数组存储,下面以简单的编解码函数说明两种编码格式的差异。

MapboxGL:

function mapboxEncode(height: number) {
  const value = Math.floor((height + 10000) * 10);
  const r = value >> 16;
  const g = value >> 8 & 0x0000FF;
  const b = value & 0x0000FF;
  return [r, g, b];
}

function mapboxDecode(
  color: [number, number, number]
) {
  return -10000 + ((color[0] * 256 * 256 + color[1] * 256 + color[2]) * 0.1);
}

terrarium:

function terrariumEncode(height: number) {
  height += 32768;
  const r = Math.floor(height / 256.0);
  const g = Math.floor(height % 256);
  const b = Math.floor((height - Math.floor(height)) * 256.0);
  return [r, g, b];
}

function terrariumDecode(
  color: [number, number, number]
) {
  return (color[0] * 256 + color[1] + color[2] / 256.0) - 32768;
}

对于 cesium 的地形编码和解码:

// 每个点像素值是 int16
function cesiumEncode(height: number) {
  return Math.floor((height + 1000) / 0.2);
}

function cesiumDecode(pixel: number){
  return (pixel * 0.2) - 1000;
}