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

map_3d_vis2025-12-11 16:06

在实际项目中，我们经常需要加载各种标准地图服务，比如 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 请求获取地图图片。

基本使用

js 复制代码 
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 更好。

基本使用

js 复制代码 
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 模板直接访问瓦片，支持各种自定义瓦片服务。

基本使用

js 复制代码 
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 标准）
js 复制代码 
// 使用 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 示例

js 复制代码 
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 来限制瓦片的缩放级别范围。

第四步：理解切图规则

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

坐标系和原点

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

  1. 屏幕坐标系（左上角原点）

    • X 轴：从左到右递增
    • Y 轴：从上到下递增
    • 原点在左上角
    • 如：谷歌地图、OpenStreetMap

  2. 地理坐标系（左下角原点）

    • X 轴：从左到右递增
    • Y 轴：从下到上递增
    • 原点在左下角
    • 如：TMS（Tile Map Service）标准

如何判断使用哪种规则

我的经验：

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

瓦片坐标计算

我的理解：

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

第五步：完整示例

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

js 复制代码 
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 地图不显示

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

解决：

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

坑 2：WMTS 瓦片位置错乱

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

解决：

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

坑 3：XYZ 瓦片上下颠倒

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

解决：

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

坑 4：瓦片加载很慢

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

解决：

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

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

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

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

我的学习总结

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

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

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

下一步计划：

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

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

相关推荐
map_3d_vis2 天前
JSAPIThree 加载天地图学习笔记：使用天地图影像服务
学习笔记·初学者·天地图·mapvthree·jsapithree·tianditu·tiandituimagerytileprovider
map_3d_vis6 天前
JSAPIThree 加载 Mapbox 数据学习笔记：使用 Mapbox 矢量瓦片地图
学习笔记·mvt·mapbox·矢量瓦片·初学者·mapvthree·jsapithree·mapboxvectortileprovider
map_3d_vis7 天前
JSAPIThree 加载 Cesium 数据学习笔记：使用 Cesium 地形和影像服务
学习笔记·cesium·地形·初学者·terrain·mapvthree·jsapithree·cesiumterraintileprovider
map_3d_vis9 天前
JSAPIThree 数据源系统学习笔记：让数据在地图上可视化
json·学习笔记·csv·geojson·datasource·数据源·初学者·mapvthree·jsapithree
map_3d_vis13 天前
JSAPIThree 天空和天气系统学习笔记：营造真实的环境氛围
学习笔记·天气系统·初学者·mapvthree·jsapithree·天空系统·defaultsky·dynamicsky·staticsky·dynamicweather
map_3d_vis14 天前
JSAPIThree UI 控件学习笔记：用内置控件提升交互
学习笔记·zoom·初学者·compass·ui控件·mapvthree·jsapithree·enginewidgets·exportimage
map_3d_vis15 天前
JSAPIThree 事件系统学习笔记：处理交互的基础
点击事件·3d地图·mapvthreejsapithree
mapvthree16 天前
mapvthree 地理投影设计分析——自动转换与统一接口的设计理念
坐标系统·mapvthree·二三维一体化·地理投影·设计理念
map_3d_vis16 天前
JSAPIThree 标签使用学习笔记：在地图上添加文字和图标
学习笔记·标签·label·初学者·mapvthree·jsapithree·文字标签·图标标签
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03UV安装并设置国内源04【AutoGLM部署】本地私有化部署AI手机Agent05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06React CVE-2025-55182漏洞排查与修复指南07Linux下V2Ray安装配置指南08BongoCat - 跨平台键盘猫动画工具09在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）10从入门到实战：Gemini 3 使用指南速览