Cobe项目API详解：创建3D地球可视化效果

滑思眉Philip

于 2025-06-11 09:04:01 发布

阅读量374

点赞数 3

本文链接：https://blog.csdn.net/gitblog_00218/article/details/148575830

版权

Cobe项目API详解：创建3D地球可视化效果

cobe 5kB WebGL globe lib. 项目地址: https://gitcode.com/gh_mirrors/co/cobe

概述

Cobe是一个轻量级的WebGL库，专门用于在网页上创建精美的3D地球可视化效果。本文将深入解析Cobe的核心API，帮助开发者快速掌握如何创建和自定义3D地球。

核心API：createGlobe函数

Cobe库导出一个名为createGlobe的默认函数，这是创建3D地球的入口点。该函数接受两个必需参数并返回一个地球实例：

import createGlobe from 'cobe'

const globe = createGlobe(canvas, options)

参数详解

1. canvas参数

canvas参数是一个HTML Canvas元素，必须预先定义好其宽度(width)和高度(height)。这个Canvas元素将作为3D地球的渲染容器。

技术要点：

确保Canvas元素已添加到DOM中
建议使用CSS设置Canvas的尺寸，同时通过属性设置其渲染尺寸
对于响应式设计，需要监听窗口大小变化并调整Canvas尺寸

2. options参数

options是一个配置对象，包含控制地球外观和行为的各种属性。以下是主要属性的详细说明：

基本显示属性

| 属性 | 描述 | 是否必需 | 取值范围 | |------|------|---------|----------| | width | Canvas的宽度(像素) | 是 | 正整数 | | height | Canvas的高度(像素) | 是 | 正整数 | | devicePixelRatio | 设备像素比(DPR) | 否 | 正数，默认1 | | scale | 地球缩放比例 | 否 | 正数 | | offset | 地球在Canvas中的偏移量 | 否 | [x, y]数组 |

光照与颜色

| 属性 | 描述 | 是否必需 | 取值范围 | |------|------|---------|----------| | dark | 暗黑模式强度 | 是 | 0-1 | | diffuse | 漫反射光照强度 | 是 | 正数 | | baseColor | 基础颜色(RGB数组) | 否 | [r,g,b], 0-1 | | glowColor | 发光颜色(RGB数组) | 否 | [r,g,b], 0-1 |

地图点设置

| 属性 | 描述 | 是否必需 | 取值范围 | |------|------|---------|----------| | mapSamples | 显示的点数 | 是 | 0-100000 | | mapBrightness | 点的亮度 | 是 | 正数 | | mapBaseBrightness | 非地图区域的亮度 | 否 | 正数 |

视角控制

| 属性 | 描述 | 是否必需 | 取值范围 | |------|------|---------|----------| | phi | 经度角度(φ) | 是 | 0-2π | | theta | 纬度角度(θ) | 是 | -π到π |

其他属性

| 属性 | 描述 | 是否必需 | |------|------|---------| | opacity | 透明度 | 否 | | onRender | 渲染回调函数 | 是 | | markers | 标记点数组 | 否 |

标记点(markers)详解

标记点用于在地球上突出显示特定位置。每个标记点是一个包含以下属性的对象：

markers: [
  // 使用全局markerColor
  { location: [纬度, 经度], size: 大小 },
  // 使用自定义颜色
  { location: [纬度, 经度], size: 大小, color: [r, g, b] }
]

技术要点：

location是[纬度, 经度]数组，纬度范围-90到90，经度范围-180到180
size控制标记点的大小，建议值0.01-0.1
color是可选的RGB数组，值范围0-1

渲染回调(onRender)

onRender是一个重要的回调函数，在每一帧渲染时被调用。开发者可以在此函数中更新地球状态，实现动画效果。

let rotationAngle = 0;

const globe = createGlobe(canvas, {
  // ...其他配置
  onRender: (state) => {
    // 更新旋转角度
    state.phi = rotationAngle;
    
    // 每帧旋转0.01弧度
    rotationAngle += 0.01;
    
    // 可以在此添加其他动态效果
    state.dark = Math.sin(Date.now() * 0.001) * 0.5 + 0.5;
  }
});