JSAPIThree 加载 WMS、WMTS 和通用栅格图学习笔记：标准地图服务与切图规则

原创

用户11918068

发布于 2025-12-11 15:57:39

1740

文章被收录于专栏：JSAPIThreeJSAPIThree

在实际项目中，我们经常需要加载各种标准地图服务，比如 WMS、WMTS，或者自定义的 XYZ 格式瓦片。今天就来学习一下如何在 mapvthree 中使用这些服务，以及理解不同的瓦片切图规则。

了解标准地图服务

在 GIS 领域，有几种常见的地图服务标准：

WMS（Web Map Service）：Web 地图服务，通过 HTTP 请求获取地图图片
WMTS（Web Map Tile Service）：Web 地图瓦片服务，提供预切好的瓦片
XYZ：通用的瓦片格式，通过 URL 模板直接访问瓦片

我的理解：WMS 是动态生成地图图片，WMTS 和 XYZ 是使用预切好的瓦片，性能更好。

第一步：加载 WMS 服务

WMS 是 OGC 标准的 Web 地图服务，通过参数化的 HTTP 请求获取地图图片。

基本使用

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [120.628, 27.786],
        range: 500000,
        provider: null,
        projection: 'EPSG:3857',
    },
});

// 添加 WMS 服务
const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.WMSImageryTileProvider({
        url: 'https://ows.mundialis.de/services/service',
        params: {
            LAYERS: 'TOPO-WMS,OSM-Overlay-WMS',
            SRS: 'EPSG:3857',
            VERSION: '1.1.1',
            WIDTH: 256,
            HEIGHT: 256,
        },
    }),
}));

我的发现：WMS 需要配置服务 URL 和请求参数，包括图层名称、坐标系、版本等。

参数说明：

url：WMS 服务地址
params.LAYERS：要加载的图层名称，多个图层用逗号分隔
params.SRS：空间参考系统，常用 EPSG:3857（Web 墨卡托）或 EPSG:4326（WGS84）
params.VERSION：WMS 版本，常用 1.1.1 或 1.3.0
params.WIDTH 和 params.HEIGHT：请求图片的尺寸，通常为 256

第二步：加载 WMTS 服务

WMTS 是 OGC 标准的 Web 地图瓦片服务，提供预切好的瓦片，性能比 WMS 更好。

基本使用

const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.WMTSImageryTileProvider({
        url: 'https://mrdata.usgs.gov/mapcache/wmts?LAYER=sgmc2&TILEMATRIX={z}',
        params: {
            STYLE: 'default',
            TILEMATRIXSET: 'GoogleMapsCompatible',
            VERSION: '1.0.0',
            FORMAT: 'image/png',
        },
    }),
}));

我的发现：WMTS 的 URL 中可以使用 {z} 占位符，引擎会自动替换为对应的缩放级别。

参数说明：

url：WMTS 服务地址，可以使用 {z}、{x}、{y} 占位符
params.STYLE：图层样式
params.TILEMATRIXSET：瓦片矩阵集，常用 GoogleMapsCompatible
params.VERSION：WMTS 版本，通常为 1.0.0
params.FORMAT：图片格式，如 image/png、image/jpeg

我的理解：

WMTS 使用预切好的瓦片，加载速度更快
URL 中的占位符会在请求时被替换为实际的瓦片坐标
不同的 WMTS 服务可能有不同的参数要求

第三步：加载 XYZ 格式瓦片

XYZ 是最通用的瓦片格式，通过 URL 模板直接访问瓦片，支持各种自定义瓦片服务。

基本使用

const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://server.arcgisonline.com/ArcGIS/rest/services/' +
              'World_Topo_Map/MapServer/tile/{z}/{y}/{x}',
    }),
}));

我的发现：XYZ 格式使用 {z}/{y}/{x} 占位符，分别代表缩放级别、行号、列号。

切图规则：y 和 reverseY

不同的瓦片服务可能使用不同的切图规则，主要体现在 Y 轴的起始位置：

y（默认）：Y 轴从左上角开始，向下递增（如谷歌地图）
reverseY：Y 轴从左下角开始，向上递增（如 TMS 标准）

// 使用 y 规则（左上角为原点）
const mapView1 = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://example.com/tiles/{z}/{x}/{y}.png',
        // 默认使用 y 规则
    }),
}));

// 使用 reverseY 规则（左下角为原点，TMS 标准）
const mapView2 = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://example.com/tms/{z}/{x}/{reverseY}.png',
        // 使用 reverseY 占位符
    }),
}));

我的理解：

如果瓦片服务使用左上角为原点（Y 向下递增），使用 {y}
如果瓦片服务使用左下角为原点（Y 向上递增，TMS 标准），使用 {reverseY}
使用错误的规则会导致瓦片位置错乱

TMS 示例

const mapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://mapopen-pub-jsapigl.bj.bcebos.com/tms-bj/{z}/{x}/{reverseY}.png',
        startLevel: 7,
        maxLevel: 12,
    }),
}));

我的发现：可以设置 startLevel 和 maxLevel 来限制瓦片的缩放级别范围。

第四步：理解切图规则

作为一个初学者，理解切图规则很重要，这决定了瓦片能否正确显示。

坐标系和原点

地图瓦片通常使用两种坐标系：

屏幕坐标系（左上角原点）
- X 轴：从左到右递增
- Y 轴：从上到下递增
- 原点在左上角
- 如：谷歌地图、OpenStreetMap
地理坐标系（左下角原点）
- X 轴：从左到右递增
- Y 轴：从下到上递增
- 原点在左下角
- 如：TMS（Tile Map Service）标准

如何判断使用哪种规则

我的经验：

查看服务文档，通常会说明使用的切图规则
如果文档没有说明，可以尝试两种规则，看哪种显示正确
常见的服务：
- 谷歌地图、OpenStreetMap：使用 y
- TMS 标准服务：使用 reverseY

瓦片坐标计算

我的理解：

z：缩放级别，数值越大，地图越详细
x：瓦片的列号，从 0 开始
y：瓦片的行号，从 0 开始
在缩放级别 z 下，总共有 2^z × 2^z 个瓦片

第五步：完整示例

我想写一个完整的示例，展示三种服务的使用：

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [120.628, 27.786],
        range: 500000,
        provider: null,
        projection: 'EPSG:3857',
    },
});

// 示例 1：WMS 服务
const wmsMapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.WMSImageryTileProvider({
        url: 'https://ows.mundialis.de/services/service',
        params: {
            LAYERS: 'TOPO-WMS',
            SRS: 'EPSG:3857',
            VERSION: '1.1.1',
            WIDTH: 256,
            HEIGHT: 256,
        },
    }),
}));

// 示例 2：WMTS 服务
const wmtsMapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.WMTSImageryTileProvider({
        url: 'https://mrdata.usgs.gov/mapcache/wmts?LAYER=sgmc2&TILEMATRIX={z}',
        params: {
            STYLE: 'default',
            TILEMATRIXSET: 'GoogleMapsCompatible',
            VERSION: '1.0.0',
            FORMAT: 'image/png',
        },
    }),
}));

// 示例 3：XYZ 格式（y 规则）
const xyzMapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://server.arcgisonline.com/ArcGIS/rest/services/' +
              'World_Topo_Map/MapServer/tile/{z}/{y}/{x}',
    }),
}));

// 示例 4：XYZ 格式（reverseY 规则，TMS）
const tmsMapView = engine.add(new mapvthree.MapView({
    imageryProvider: new mapvthree.XYZImageryTileProvider({
        url: 'https://mapopen-pub-jsapigl.bj.bcebos.com/tms-bj/{z}/{x}/{reverseY}.png',
        startLevel: 7,
        maxLevel: 12,
    }),
}));

我的感受：掌握了这三种服务的使用方法，就可以加载各种标准地图服务了！

第六步：踩过的坑

作为一个初学者，我踩了不少坑，记录下来避免再犯：

坑 1：WMS 地图不显示

原因：参数配置错误，比如图层名称不对、坐标系不匹配。

解决：

检查 WMS 服务的 GetCapabilities 文档，确认正确的参数
确保 SRS 参数与引擎的投影设置一致
确认 LAYERS 参数中的图层名称正确

坑 2：WMTS 瓦片位置错乱

原因：URL 占位符使用错误，或者 TILEMATRIXSET 不匹配。

解决：

确认 URL 中的占位符格式正确（{z}、{x}、{y}）
检查 TILEMATRIXSET 是否与服务提供的一致
查看服务的 GetCapabilities 文档

坑 3：XYZ 瓦片上下颠倒

原因：切图规则选择错误，应该用 y 却用了 reverseY，或者相反。

解决：

查看服务文档，确认使用的切图规则
如果文档没有说明，尝试两种规则，看哪种显示正确
记住：左上角原点用 y，左下角原点用 reverseY

坑 4：瓦片加载很慢

原因：服务地址访问慢，或者网络问题。

解决：

检查服务地址是否可访问
考虑使用 CDN 加速
对于自定义服务，确保服务器性能足够

坑 5：某些缩放级别没有瓦片

原因：服务只提供了特定缩放级别的瓦片。

解决：使用 startLevel 和 maxLevel 限制缩放级别范围。

我的学习总结

经过这一天的学习，我掌握了：

WMS 服务：动态生成地图图片，需要配置服务 URL 和请求参数
WMTS 服务：使用预切好的瓦片，性能更好，支持 URL 占位符
XYZ 格式：最通用的瓦片格式，支持自定义服务
切图规则：理解 y 和 reverseY 的区别，正确选择切图规则
参数配置：了解各种服务的参数含义和配置方法

我的感受：标准地图服务虽然配置有点复杂，但是用起来其实不难。关键是要理解不同服务的特点，然后正确配置参数和切图规则！

下一步计划：

学习更多地图服务的配置选项
尝试创建自定义的瓦片服务
做一个完整的地图展示项目

学习笔记就到这里啦！作为一个初学者，我觉得标准地图服务虽然配置有点复杂，但是用起来其实不难。关键是要理解不同服务的特点，然后正确配置参数和切图规则！希望我的笔记能帮到其他初学者！大家一起加油！

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

学习笔记

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

登录后参与评论

0 条评论

热度