<!-- Three.js WebGPU 地球可视化项目
📋 项目概述
这是一个基于Three.js WebGPU实现的交互式3D地球可视化应用，展示了现代Web图形技术的能力。项目通过先进的着色器技术和物理渲染，创造了一个具有真实感的地球模型，包含动态大气层、昼夜交替、云层效果等高级视觉效果。

🎯 主要功能
1. 真实感地球渲染
昼夜交替系统：根据太阳位置平滑过渡白天和夜晚纹理

动态大气层：大气颜色随太阳方向变化（蓝色白天 ↔ 橙红色黄昏）

云层效果：半透明云层覆盖，云层区域会增亮表面

地形凹凸：使用法线贴图模拟真实的地形起伏

2. 物理渲染特性
菲涅尔效应：地球边缘产生自然的光晕效果

粗糙度控制：不同表面区域具有不同的粗糙度值

光照模型：基于物理的光照计算，模拟真实光照效果

3. 交互功能
轨道控制：支持鼠标拖拽旋转、滚轮缩放、右键平移

实时调试：通过GUI面板调节颜色、粗糙度等参数

地球自转：自动缓慢旋转，模拟真实地球自转

4. 视觉效果
高分辨率纹理：4096×4096像素的高清地球纹理

平滑过渡：所有状态变化都使用平滑插值函数

透明度混合：大气层使用透明度混合实现渐变效果

🔧 核心技术点
1. WebGPU渲染
javascript
// 使用下一代图形API WebGPU
renderer = new THREE.WebGPURenderer();
性能优势：比WebGL更高效，支持并行计算

现代特性：支持最新的图形硬件特性

类型化数组：使用GPU友好的数据类型

2. TSL着色器语言
javascript
import { texture, mix, bumpMap, normalWorldGeometry } from 'three/tsl';
节点化编程：可视化着色器节点连接

类型安全：编译时类型检查

模块化：可重用的着色器组件

3. 物理渲染流程
text
纹理加载 → 法线计算 → 光照计算 → 菲涅尔计算 → 颜色混合 → 输出
4. 着色器算法
4.1 菲涅尔效应计算
javascript
// 视线方向与法线点积 → 菲涅尔系数
const fresnel = viewDirection.dot(normalWorldGeometry).abs().oneMinus();
4.2 昼夜过渡
javascript
// 平滑阶梯函数实现自然过渡
const dayStrength = sunOrientation.smoothstep(-0.25, 0.5);
4.3 多层纹理混合
javascript
// 基础颜色 + 云层 + 大气层 三层混合
finalOutput = mix(纹理颜色, 大气颜色, 混合系数);
5. 纹理系统
javascript
// 多通道纹理应用
texture(bumpRoughnessCloudsTexture) // RGB通道分别存储：
// R: 凹凸高度    G: 粗糙度    B: 云层遮罩
6. 性能优化
各向异性过滤：anisotropy = 8 提高纹理质量

设备像素比适配：setPixelRatio() 适配高DPI屏幕

高效的动画循环：使用setAnimationLoop()

📊 技术架构
1. 数据流架构
text
用户输入 → 轨道控制器 → 相机更新
时间增量 → 地球自转 → 着色器uniform更新
窗口调整 → 相机/渲染器尺寸更新
2. 着色器节点网络
text
[太阳方向] → [昼夜计算] → [颜色混合]
[视线方向] → [菲涅尔计算] → [大气透明度]
[基础纹理] → [云层叠加] → [最终输出]
[法线贴图] → [凹凸效果] → [光照响应]
3. 材质系统分层
text
Layer 1: MeshStandardNodeMaterial (基础地球材质)
Layer 2: MeshBasicNodeMaterial (大气层材质，背面渲染)
🎨 视觉特效实现
1. 大气层效果
边缘光晕：基于菲涅尔效应

颜色过渡：太阳方向驱动的颜色插值

透明度渐变：视线角度相关的透明度变化

2. 云层系统
强度计算：从纹理B通道提取

增亮效果：云层区域增加亮度

粗糙度影响：云层区域调整表面粗糙度

3. 光照响应
太阳方向计算：点积判断光照强度

物理光照模型：基于真实物理的光照计算

环境响应：表面特性对光照的响应

🛠️ 开发工具与调试
1. 调试界面
javascript
// 创建参数面板
const gui = renderer.inspector.createParameters('参数设置');
实时调节：颜色、粗糙度等参数可实时调整

即时反馈：修改立即反映在渲染结果中

用户友好：直观的UI控件

2. 性能监控
WebGPU性能：利用硬件加速

内存管理：纹理压缩和缓存

渲染优化：避免不必要的重绘

🌐 兼容性与部署
1. 浏览器支持
Chrome 113+：完整WebGPU支持

Edge 113+：基于Chromium，支持良好

Firefox：实验性支持（需启用标志）

2. 资源加载
纹理预加载：高分辨率纹理异步加载

错误处理：加载失败的回退机制

缓存策略：浏览器缓存纹理资源

🚀 项目亮点
技术前沿性：使用WebGPU等最新Web图形技术

视觉效果：电影级的渲染质量和真实感

交互体验：流畅的用户交互和实时反馈

代码质量：模块化、注释完善的代码结构

可扩展性：易于添加新特效和功能

📈 性能表现
帧率：在中等配置设备上保持60FPS

内存使用：高效纹理压缩，约50MB内存占用

加载时间：纹理异步加载，快速显示初始场景

GPU利用率：合理利用GPU并行计算能力 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题 - 显示为浏览器标签页标题 -->
		<title>Three.js WebGPU - 地球可视化</title>
		<!-- 字符编码设置 - 使用UTF-8支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 
			视口设置 (Viewport):
			- width=device-width: 宽度等于设备宽度
			- user-scalable=no: 禁止用户缩放（确保WebGL渲染正确）
			- minimum-scale=1.0: 最小缩放比例为1.0倍
			- maximum-scale=1.0: 最大缩放比例为1.0倍
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式表，用于页面布局和样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>
	<body>

		<!-- 
			信息面板容器
			id="info": 用于CSS样式和JavaScript操作的标识符
			这个div将显示在3D场景上方的信息层
		-->
		<div id="info">
			<!-- 
				Three.js官方网站链接
				- href: 链接地址
				- target="_blank": 在新标签页打开
				- rel="noopener": 安全设置，防止新页面访问原页面的window对象
				- class="logo-link": CSS类名，通常用于设置Three.js图标样式
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装器 - 用于组织标题内容 -->
			<div class="title-wrapper">
				<!-- 主标题链接 - 点击可访问Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 副标题文本 - 显示当前示例名称 -->
				<span>地球可视化示例</span>
			</div>

			<!-- 
				小字号文本区域 - 显示版权信息和数据来源
				<small>标签表示旁注或小字号文本
			-->
			<small>
				<!-- 基于Three.js Journey教程的说明 -->
				基于 <a href="https://threejs-journey.com/lessons/earth-shaders" target="_blank" rel="noopener">Three.js Journey</a> 教程制作
				<br>
				<!-- 地球纹理数据的来源说明 -->
				地球纹理数据来自 <a href="https://www.solarsystemscope.com/textures/" target="_blank" rel="noopener">Solar System Scope</a>（已调整尺寸和合并）
			</small>
		</div>

		<!-- 
			导入映射表 (Import Map)
			type="importmap": 定义JavaScript模块的导入路径映射
			浏览器将使用这些映射来解析模块导入语句
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module": 表示这是一个ES6模块，支持import/export语法
			模块中的代码会在HTML解析后执行
		-->
		<script type="module">

			// ==================== 模块导入部分 ====================
			// 导入Three.js核心模块的WebGPU版本
			// * as THREE: 将整个模块导入为THREE命名空间对象
			import * as THREE from 'three/webgpu';
			
			// 导入TSL（Three.js着色器语言）的着色器节点函数
			// 这些函数用于在节点材质中构建着色器网络
			import { 
				step,          // 阶梯函数：step(edge, x) 当x<edge返回0，否则返回1
				normalWorldGeometry, // 世界坐标系中的几何法线向量
				output,        // 材质输出节点
				texture,       // 纹理采样节点
				vec3,          // 三维向量构造函数
				vec4,          // 四维向量构造函数
				normalize,     // 向量归一化函数
				positionWorld, // 世界坐标系中的顶点位置
				bumpMap,       // 凹凸贴图节点
				cameraPosition,// 相机在世界坐标系中的位置
				color,         // 颜色构造函数
				uniform,       // 创建uniform变量节点
				mix,           // 线性插值函数：mix(x, y, a) = x*(1-a) + y*a
				uv,            // UV坐标节点
				max            // 最大值函数
			} from 'three/tsl';

			// 导入轨道控制器 - 允许用户用鼠标旋转、缩放、平移视图
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入调试检查器 - 用于调试场景、材质参数
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// ==================== 全局变量声明 ====================
			// 这些变量在整个模块中共享
			let camera;    // Three.js相机对象，定义视图的观察方式
			let scene;     // Three.js场景对象，包含所有3D对象、光源等
			let renderer;  // WebGPU渲染器对象，负责将3D场景绘制到canvas
			let controls;  // 轨道控制器对象，处理用户交互
			let globe;     // 地球网格对象
			let clock;     // THREE.Clock对象，用于精确的时间计算和动画

			// ==================== 初始化函数调用 ====================
			// 页面加载完成后调用初始化函数
			init();

			// ==================== 初始化函数定义 ====================
			function init() {

				// 1. 创建时钟对象
				// THREE.Clock用于跟踪时间，特别适合需要基于时间差的动画
				clock = new THREE.Clock();

				// 2. 创建透视相机 (PerspectiveCamera)
				// 透视相机模拟人眼观察方式，近大远小
				camera = new THREE.PerspectiveCamera(
					25,                         // 视野角度 (Field of View) - 25度
					window.innerWidth / window.innerHeight, // 宽高比 - 根据窗口大小计算
					0.1,                        // 近裁剪面 - 相机能看到的最近距离
					100                         // 远裁剪面 - 相机能看到的最远距离
				);
				// 设置相机初始位置 (x, y, z)
				// x: 水平方向，y: 垂直方向，z: 深度方向
				camera.position.set(4.5, 2, 3);

				// 3. 创建场景
				// 场景是所有3D对象的容器，包括网格、光源、相机等
				scene = new THREE.Scene();

				// 4. 创建光源 - 模拟太阳
				// 平行光 (DirectionalLight) 类似于太阳光，所有光线平行
				const sun = new THREE.DirectionalLight('#ffffff', 2); // 参数：颜色，强度
				sun.position.set(0, 0, 3);      // 设置光源位置 (x, y, z)
				scene.add(sun);                 // 将光源添加到场景中

				// 5. 创建Uniform变量
				// Uniform是着色器中的全局变量，可以在CPU和GPU之间传递数据
				// uniform()函数创建可以在TSL节点材质中使用的uniform节点
				const atmosphereDayColor = uniform(color('#4db2ff'));     // 白天大气颜色 - 浅蓝色
				const atmosphereTwilightColor = uniform(color('#bc490b')); // 黄昏大气颜色 - 橙红色
				const roughnessLow = uniform(0.25);  // 粗糙度最小值 - 控制材质表面的微粗糙度
				const roughnessHigh = uniform(0.35); // 粗糙度最大值

				// 6. 加载纹理
				// THREE.TextureLoader用于异步加载图像纹理
				const textureLoader = new THREE.TextureLoader();

				// 加载白天地球纹理
				// 这是一张4096x4096像素的高分辨率地球日间图像
				const dayTexture = textureLoader.load('./textures/planets/earth_day_4096.jpg');
				dayTexture.colorSpace = THREE.SRGBColorSpace; // 设置颜色空间为sRGB，显示更自然
				dayTexture.anisotropy = 8; // 设置各向异性过滤级别，提高纹理在倾斜角度的质量

				// 加载夜晚地球纹理
				// 显示地球夜间的城市灯光
				const nightTexture = textureLoader.load('./textures/planets/earth_night_4096.jpg');
				nightTexture.colorSpace = THREE.SRGBColorSpace;
				nightTexture.anisotropy = 8;

				// 加载组合纹理
				// 这个纹理包含三个通道的混合信息：
				// R通道: 地形凹凸/高度图 (Bump Map)
				// G通道: 粗糙度图 (Roughness Map)
				// B通道: 云层遮罩 (Clouds Mask)
				const bumpRoughnessCloudsTexture = textureLoader.load('./textures/planets/earth_bump_roughness_clouds_4096.jpg');
				bumpRoughnessCloudsTexture.anisotropy = 8;

				// 7. 计算菲涅尔效应 (Fresnel Effect)
				// 菲涅尔效应：物体表面反射率随观察角度变化，边缘反射更强烈
				// 1) 计算视线方向：从相机指向表面点的向量
				const viewDirection = positionWorld.sub(cameraPosition).normalize();
				// 2) 计算菲涅尔系数：视线方向与法线点积的绝对值，然后1减去该值
				//    dot()计算点积，abs()取绝对值，oneMinus()计算1-x，toVar()存储为变量
				const fresnel = viewDirection.dot(normalWorldGeometry).abs().oneMinus().toVar();

				// 8. 计算太阳方向与表面法线的点积
				// 这个值表示太阳光照强度：1表示直射，0表示垂直，-1表示背面
				const sunOrientation = normalWorldGeometry.dot(normalize(sun.position)).toVar();

				// 9. 计算大气颜色
				// 根据太阳方向在黄昏色和白天色之间平滑过渡
				// smoothstep(-0.25, 0.75)创建平滑的过渡函数
				const atmosphereColor = mix(
					atmosphereTwilightColor,      // 起始颜色（黄昏）
					atmosphereDayColor,           // 结束颜色（白天）
					sunOrientation.smoothstep(-0.25, 0.75) // 混合系数（基于太阳方向）
				);

				// 10. 创建地球材质
				// MeshStandardNodeMaterial是基于物理渲染(PBR)的节点材质
				const globeMaterial = new THREE.MeshStandardNodeMaterial();

				// 11. 提取云层强度
				// 从组合纹理的B通道（蓝色通道）提取云层信息
				// uv()获取当前片元的UV坐标，b获取蓝色通道值
				// smoothstep(0.2, 1)将值平滑映射到0-1范围
				const cloudsStrength = texture(bumpRoughnessCloudsTexture, uv()).b.smoothstep(0.2, 1);

				// 12. 设置地球基础颜色
				// 混合白天纹理和白色，云层区域更亮
				globeMaterial.colorNode = mix(
					texture(dayTexture), // 基础白天纹理
					vec3(1),             // 纯白色 (1,1,1)
					cloudsStrength.mul(2) // 云层强度乘以2作为混合系数
				);

				// 13. 计算粗糙度
				// 使用组合纹理的G通道（绿色通道）作为基础粗糙度
				// step(0.01, cloudsStrength): 如果云层强度>0.01返回1，否则返回0
				// max(): 取两者最大值，确保云层区域也有足够的粗糙度
				const roughness = max(
					texture(bumpRoughnessCloudsTexture).g, // 基础地形粗糙度
					step(0.01, cloudsStrength)             // 云层区域粗糙度
				);
				// 将粗糙度值从[0,1]范围重新映射到[roughnessLow, roughnessHigh]范围
				// remap(输入最小值, 输入最大值, 输出最小值, 输出最大值)
				globeMaterial.roughnessNode = roughness.remap(0, 1, roughnessLow, roughnessHigh);

				// 14. 加载夜晚纹理
				const night = texture(nightTexture);
				
				// 15. 计算白天强度
				// 根据太阳方向计算昼夜过渡
				// 太阳方向在-0.25到0.5之间平滑过渡
				const dayStrength = sunOrientation.smoothstep(-0.25, 0.5);

				// 16. 计算白天大气强度
				// 太阳方向在-0.5到1之间平滑过渡
				const atmosphereDayStrength = sunOrientation.smoothstep(-0.5, 1);
				
				// 17. 计算大气混合系数
				// 大气效果 = 白天大气强度 × 菲涅尔系数的平方
				// pow(2): 平方运算，clamp(0,1): 限制在0-1范围
				const atmosphereMix = atmosphereDayStrength.mul(fresnel.pow(2)).clamp(0, 1);

				// 18. 计算最终输出颜色
				// 第一步：混合夜晚纹理和当前材质颜色（基于白天强度）
				let finalOutput = mix(night.rgb, output.rgb, dayStrength);
				// 第二步：在大气区域混合大气颜色
				finalOutput = mix(finalOutput, atmosphereColor, atmosphereMix);

				// 19. 设置材质最终输出
				// vec4()创建四维向量(R,G,B,A)，A通道保持原来的透明度
				globeMaterial.outputNode = vec4(finalOutput, output.a);

				// 20. 计算凹凸高度
				// 使用组合纹理的R通道（红色通道）作为地形高度
				// 或者云层强度（两者取最大值）
				const bumpElevation = max(
					texture(bumpRoughnessCloudsTexture).r, // 地形高度图
					cloudsStrength                         // 云层高度
				);
				// 设置法线贴图 - 根据高度图修改表面法线，产生凹凸感
				globeMaterial.normalNode = bumpMap(bumpElevation);

				// 21. 创建地球几何体和网格
				// SphereGeometry: 球体几何体
				// 参数：半径1，宽度分段数64，高度分段数64
				const sphereGeometry = new THREE.SphereGeometry(1, 64, 64);
				// Mesh: 网格对象，将几何体和材质组合
				globe = new THREE.Mesh(sphereGeometry, globeMaterial);
				scene.add(globe); // 将地球添加到场景

				// 22. 创建大气层材质
				// MeshBasicNodeMaterial: 基础节点材质，不受光照影响
				const atmosphereMaterial = new THREE.MeshBasicNodeMaterial({ 
					side: THREE.BackSide, // 只渲染背面（球体内侧）
					transparent: true     // 启用透明度
				});
				
				// 23. 计算大气透明度
				// 第一步：将菲涅尔值从[0.73,1]重新映射到[1,0]并取立方
				let alpha = fresnel.remap(0.73, 1, 1, 0).pow(3);
				// 第二步：乘以太阳方向影响系数
				alpha = alpha.mul(sunOrientation.smoothstep(-0.5, 1));
				// 设置大气材质输出：大气颜色和计算出的透明度
				atmosphereMaterial.outputNode = vec4(atmosphereColor, alpha);

				// 24. 创建大气层网格
				// 使用相同球体几何体但稍大的尺寸
				const atmosphere = new THREE.Mesh(sphereGeometry, atmosphereMaterial);
				atmosphere.scale.setScalar(1.04); // 等比缩放1.04倍，比地球稍大
				scene.add(atmosphere);            // 添加到场景

				// 25. 创建WebGPU渲染器
				// THREE.WebGPURenderer: 基于WebGPU API的渲染器（下一代图形API）
				renderer = new THREE.WebGPURenderer();
				// 设置设备像素比，适应高DPI屏幕（Retina显示屏等）
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器尺寸为窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环回调函数（类似requestAnimationFrame）
				renderer.setAnimationLoop(animate);
				// 创建调试检查器并附加到渲染器
				renderer.inspector = new Inspector();
				// 将渲染器的canvas元素添加到DOM的body中
				document.body.appendChild(renderer.domElement);

				// 26. 创建轨道控制器
				// OrbitControls: 允许用户通过鼠标交互控制相机
				controls = new OrbitControls(camera, renderer.domElement);
				controls.enableDamping = true;     // 启用阻尼效果（惯性）
				controls.minDistance = 0.1;        // 最小缩放距离（相机离目标最近距离）
				controls.maxDistance = 50;         // 最大缩放距离（相机离目标最远距离）

				// 27. 添加窗口大小变化事件监听器
				// 当浏览器窗口大小变化时，调整相机和渲染器
				window.addEventListener('resize', onWindowResize);

				// 28. 创建调试图形用户界面(GUI)
				// 通过检查器创建参数面板
				const gui = renderer.inspector.createParameters('参数设置');

				// 添加白天大气颜色控制器
				gui
					.addColor(
						{ 
							// 获取当前颜色的十六进制值（sRGB颜色空间）
							color: atmosphereDayColor.value.getHex(THREE.SRGBColorSpace) 
						}, 
						'color' // 控制的属性名
					)
					// 当颜色值改变时的回调函数
					.onChange((value) => {
						// 更新uniform变量的值
						atmosphereDayColor.value.set(value);
					})
					.name('白天大气颜色'); // 控制器在GUI中显示的名称

				// 添加黄昏大气颜色控制器
				gui
					.addColor({ color: atmosphereTwilightColor.value.getHex(THREE.SRGBColorSpace) }, 'color')
					.onChange((value) => {
						atmosphereTwilightColor.value.set(value);
					})
					.name('黄昏大气颜色');

				// 添加粗糙度最小值控制器
				// 参数：对象，属性名，最小值，最大值，步进值
				gui.add(roughnessLow, 'value', 0, 1, 0.001).name('粗糙度最小值');
				// 添加粗糙度最大值控制器
				gui.add(roughnessHigh, 'value', 0, 1, 0.001).name('粗糙度最大值');

			}

			// ==================== 窗口大小变化处理函数 ====================
			function onWindowResize() {
				// 更新相机的宽高比（匹配新的窗口尺寸）
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵（必须调用此方法使更改生效）
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸（匹配新的窗口尺寸）
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			// ==================== 动画循环函数 ====================
			async function animate() {
				// 1. 获取时间增量 (delta time)
				// getDelta()返回自上次调用以来的时间（秒）
				// 使用时间增量而不是固定值，确保动画在不同刷新率设备上一致
				const delta = clock.getDelta();
				
				// 2. 更新地球自转
				// 每秒旋转0.025弧度，约1.43度，24小时完成一圈
				globe.rotation.y += delta * 0.025;
				
				// 3. 更新轨道控制器
				// 处理阻尼效果和用户输入更新
				controls.update();

				// 4. 渲染场景
				// 将3D场景通过相机视角渲染到canvas
				renderer.render(scene, camera);
			}

		</script>
	</body>
</html>