MapLibre GL JS第27课：添加COG栅格源

📌 学习目标

• 掌握添加COG栅格源的实现方法
• 理解相关API的使用
• 能够独立完成类似功能开发

🎯 核心概念

添加外部云优化GeoTIFF（COG）作为数据源。

💻 完 整 代 码

代码示例

maplibregl.addProtocol('cog', MaplibreCOGProtocol.cogProtocol);

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/styles/osm-bright-gl-style/style.json',
    center: [11.39831, 47.26244],
    zoom: 14
});

map.on('load', () => {
    map.addSource('cogSource', {
        type: 'raster',
        url: 'cog://https://maplibre.org/maplibre-gl-js/docs/assets/cog.tif',
        tileSize: 256
    });

    map.addLayer({
        id: 'cogLayer',
        source: 'cogSource',
        type: 'raster'
    });
});

代码示例

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Add a COG raster source</title>
    <meta property="og:description" content="添加外部云优化 GeoTIFF（COG）作为源。" />
    <meta property="og:created" content="2025-06-25" />
    <meta charset='utf-8'>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css" />
    <script src="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
    <style>
        body { margin: 0; padding: 0; }
        html, body, #map { height: 100%; }
    </style>
</head>
<body>
<div id="map"></div>
<script src="https://unpkg.com/@geomatico/maplibre-cog-protocol@0.5.0/dist/index.js"></script>
<script>
    maplibregl.addProtocol('cog', MaplibreCOGProtocol.cogProtocol);

    const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/styles/osm-bright-gl-style/style.json',
        center: [11.39831, 47.26244],
        zoom: 14
    });

    map.on('load', () => {
        map.addSource('cogSource', {
            type: 'raster',
            url: 'cog://https://maplibre.org/maplibre-gl-js/docs/assets/cog.tif',
            tileSize: 256
        });

        map.addLayer({
            id: 'cogLayer',
            source: 'cogSource',
            type: 'raster'
        });
    });
</script>
</body>
</html>

🔍 代码解析

1. 注册COG协议

使用 maplibregl.addProtocol() 注册自定义协议，使地图能够解析 cog:// 协议的URL。

2. 初始化地图

使用 new maplibregl.Map() 创建地图实例，配置基本参数。本示例中心点设置在德国加米施-帕滕基兴附近。

3. 添加COG数据源

在 map.load 事件中添加 raster 类型数据源：

• type: 'raster': 指定为栅格源
• url: 'cog://...': 使用COG协议指定GeoTIFF文件URL

4. 添加栅格图层

创建 raster 类型图层引用COG数据源。

⚙️ 参数说明

参数	类型	必填	说明
container	string	是	地图容器ID
style	string	是	地图样式URL
center	number, number	否	初始中心点，默认0, 0
zoom	number	否	初始缩放级别，默认0

COG源配置

属性	类型	说明
type	string	必须为 'raster'
url	string	cog:// 协议的URL
tileSize	number	瓦片大小（通常256）

🎨 效果说明

运行代码后：

• 地图显示德国加米施-帕滕基兴区域（中心点 11.40°E, 47.26°N）
• COG栅格数据叠加在底图上显示
• 用户可正常交互（拖拽、缩放、旋转）

💡 常 见 问 题

Q1: 什么是COG（Cloud-Optimized GeoTIFF）？

A: COG是一种优化的GeoTIFF格式，支持HTTP范围请求，可按需加载数据的特定区域和分辨率。

Q2: 需要额外引入什么库？

A: 需要引入 @geomatico/maplibre-cog-protocol 库来支持COG协议。

Q3: COG和普通GeoTIFF有什么区别？

A: COG支持分块存储和多级分辨率，适合在Web上高效加载大型栅格数据。

📝 练习任务

1. 基础练习：修改COG文件URL，加载其他GeoTIFF数据
2. 进阶挑战：调整栅格图层的透明度和混合模式
3. 拓展思考：如何实现COG数据的动态样式调整？

🌟 最佳实践

1. 协议注册: 在创建地图前注册COG协议
2. 性能优化: 使用COG格式减少初始加载时间
3. 资源管理: 确保正确引入依赖库
4. 错误处理: 添加数据加载失败的fallback方案

🔗 延伸阅读

• Map API文档

• MapLibre GL JS 官方文档

• 下一课预告：将继续学习地图图层的基础知识

---

本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏