<!-- Three.js USDZ导出器 - 功能描述与技术分析
🎯 核心功能概述
1. 3D模型可视化与交互
实时3D渲染：在浏览器中使用WebGL技术渲染高质量的战损科幻头盔模型

交互式查看：用户可以通过鼠标/触摸控制模型旋转、缩放和平移

环境光照：提供真实的房间环境照明，增强模型的材质表现力

阴影效果：动态生成柔和的聚光灯阴影，增加场景的真实感

2. AR内容导出
USDZ格式转换：将Three.js场景导出为苹果AR兼容的USDZ格式

一键导出：桌面用户可通过GUI按钮导出USDZ文件

iOS AR预览：iOS设备用户可直接点击AR图标启动系统级AR预览

跨平台兼容：自动检测设备类型，提供最合适的用户体验

3. 响应式设计
自适应布局：自动调整渲染尺寸以适应不同屏幕大小

移动端优化：针对触控设备优化交互方式

高DPI支持：适配Retina等高分辨率显示屏

🔧 主要技术点详解
1. Three.js核心架构
渲染管线
javascript
// 完整的Three.js渲染流程
场景构建(Scene) → 相机设置(Camera) → 渲染器配置(Renderer) → WebGL绘制
关键组件
WebGLRenderer：基于WebGL 2.0/1.0的硬件加速渲染器

PerspectiveCamera：模拟人眼视角的透视相机

Scene图管理：层级化的3D对象容器系统

PMREM环境贴图：预过滤的Mipmap辐射环境贴图，实现高性能的全局光照

2. USDZ导出技术
USDZ格式特性
基于USD格式：Pixar的通用场景描述格式的苹果扩展

AR Quick Look：iOS系统级AR查看器支持

二进制打包：包含几何、纹理、材质等所有资产的单文件格式

导出流程
javascript
Three.js场景 → USDZExporter解析 → USD数据结构 → 二进制编码 → Blob对象 → 文件下载
3. 性能优化技术
阴影渲染优化
javascript
// 替代实时阴影的优化方案
实时阴影计算(性能低) → Canvas纹理阴影(性能高)
Canvas渐变纹理：使用2D Canvas生成径向渐变阴影贴图

Multiply混合模式：正片叠底混合实现自然的阴影叠加

静态阴影平面：预计算的阴影网格，避免每帧计算

环境光优化
RoomEnvironment预设：预定义的HDR环境光照

ACESFilmic色调映射：电影级色调映射算法，保留高光和阴影细节

纹理压缩：适当的环境贴图分辨率平衡质量和性能

4. 跨平台适配策略
设备检测与适配
javascript
// iOS设备检测逻辑
const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
iOS设备：显示AR图标，直接启动AR Quick Look

非iOS设备：显示GUI控制面板，提供导出功能

响应式布局：基于CSS的媒体查询和动态布局

用户交互适配
OrbitControls：统一的鼠标/触摸交互控制器

自适应分辨率：根据devicePixelRatio调整渲染质量

视口适配：确保移动端正确的缩放和布局

5. 模块化架构
ES6模块系统
javascript
// 清晰的模块导入结构
核心库(three) + 控制器(OrbitControls) + 加载器(GLTFLoader) + 导出器(USDZExporter)
关注点分离
初始化模块：Three.js环境设置和资源加载

渲染模块：场景绘制和更新逻辑

导出模块：USDZ转换和文件处理

UI模块：用户界面和控制逻辑

6. 图形技术细节
材质系统
MeshBasicMaterial：不受光照影响的基础材质（用于阴影）

GLTF PBR材质：基于物理的渲染材质（用于头盔模型）

CanvasTexture：动态生成的纹理资源

几何处理
PlaneGeometry：用于阴影平面的简单几何体

GLTF几何数据：包含顶点、法线、UV等完整几何信息

矩阵变换：位置、旋转、缩放的层级化变换系统

🚀 技术亮点
1. WebGL与现代浏览器的完美结合
利用WebGL 2.0的硬件加速能力

支持现代JavaScript特性（ES6+、模块化）

与浏览器原生API深度集成（File API、Canvas API）

2. AR技术栈的无缝衔接
Three.js 3D生态 → USDZ AR格式 → iOS AR生态

实现了Web 3D内容到移动AR的无缝转换

保持3D资产的保真度和材质表现

3. 开发效率与性能的平衡
使用Three.js高级抽象降低开发复杂度

通过优化技术保持高性能渲染

模块化架构便于维护和扩展 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 
			页面标题：
			three.js是一个流行的JavaScript 3D库
			WebGL是基于OpenGL ES的网页3D图形API
			USDZ是苹果公司推出的AR文件格式，用于iOS设备的增强现实体验
		-->
		<title>three.js WebGL应用 - USDZ格式导出器</title>
		
		<!-- 
			字符编码设置：
			UTF-8是一种可变长度的Unicode编码格式，支持所有语言字符
			确保页面能够正确显示中文、英文等各种字符
		-->
		<meta charset="utf-8">
		
		<!-- 
			视口设置：
			viewport是移动端浏览器的重要概念，控制页面的显示区域
			width=device-width - 使页面宽度等于设备宽度
			user-scalable=no - 禁止用户手动缩放（保持固定比例）
			minimum-scale=1.0 - 最小缩放比例为1.0（不缩小）
			maximum-scale=1.0 - 最大缩放比例为1.0（不放大）
			这样可以确保页面在移动设备上以固定比例显示，适合AR应用
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		
		<!-- 
			外部CSS文件链接：
			rel="stylesheet" 指定资源为样式表
			href="main.css" 指定样式表文件路径
			这个文件可能包含更多基础样式
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
		
		<!-- 
			内联样式表：
			这里定义了页面特有的样式规则
			内联样式优先级高于外部样式表
		-->
		<style>
			/* 
				页面主体样式：
				background-color设置页面背景颜色
				#eee是浅灰色，十六进制颜色表示法
				这种颜色提供良好的视觉对比度，同时不刺眼
			*/
			body {
				background-color: #eee;
			}
			
			/* 
				信息区域样式：
				#info是通过id选择器选中页面中的信息显示区域
				color设置文字颜色，#222是非常深的灰色（接近黑色但稍浅）
			*/
			#info {
				color: #222;
			}
			
			/* 
				超链接通用样式：
				a是元素选择器，选中所有<a>标签
				color设置链接颜色，#00f是蓝色
			*/
			a {
				color: #00f
			}
			
			/* 
				AR按钮样式：
				position: absolute - 绝对定位，脱离文档流
				bottom: 15px - 距离底部15像素
				left: calc(50% - 40px) - 水平居中
				calc()是CSS计算函数，50%是父元素宽度的一半，40px是按钮宽度的一半（因为按钮宽80px）
				这样设置可以使按钮在水平方向完美居中
			*/
			#button {
				position: absolute;
				bottom: 15px;
				left: calc(50% - 40px);
			}
		</style>
	</head>

	<body>
		<!-- 
			页面信息显示区域：
			id="info" 用于CSS样式和JavaScript操作
			这里显示应用信息和版权信息
			<br /> 是HTML换行标签
			target="_blank" 在新窗口/标签页打开链接
			rel="noopener" 安全设置，防止新页面通过window.opener访问原页面
		-->
		<div id="info">
			<!-- three.js官网链接 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">three.js</a> - USDZ格式导出器<br />
			<!-- 3D模型作者信息和链接 -->
			战损科幻头盔模型由 <a href="https://sketchfab.com/theblueturtle_" target="_blank" rel="noopener">theblueturtle_</a> 创作
		</div>

		<!-- 
			AR功能链接：
			id="link" 用于JavaScript操作
			rel="ar" 这是苹果特定的属性，告诉iOS设备这是一个AR资源链接
			href="" 初始为空，后续通过JavaScript动态设置
			download="asset.usdz" 指定下载时的默认文件名
			
			<img>标签：
			id="button" 对应CSS样式中的按钮样式
			width="100" 设置图片宽度为100像素
			src="files/arkit.png" 指定图片路径，这是苹果AR Kit的图标
			这个图片是AR功能的入口按钮
		-->
		<a id="link" rel="ar" href="" download="asset.usdz">
			<img id="button" width="100" src="files/arkit.png">
		</a>

		<!-- 
			导入映射（Import Map）：
			这是ES模块的特性，允许定义模块路径的别名
			type="importmap" 指定脚本类型为导入映射
			现代浏览器支持的特性，用于模块解析
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module" 表示这是一个ES6模块
			模块具有自己的作用域，支持import/export语法
		-->
		<script type="module">
			// ==================== 模块导入区域 ====================
			
			// 导入Three.js核心库的所有导出内容
			// * as THREE 将Three.js的所有导出作为一个名为THREE的对象导入
			// THREE现在包含了Three.js的所有核心功能
			import * as THREE from 'three';

			// 从Three.js附加组件中导入特定模块
			// OrbitControls：轨道控制器，用于鼠标/触摸控制3D场景视角
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// RoomEnvironment：房间环境，提供预设的环境光照和背景
			import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
			
			// GLTFLoader：GLTF格式加载器，GLTF是3D模型的通用格式
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// USDZExporter：USDZ格式导出器，USDZ是苹果的AR文件格式
			import { USDZExporter } from 'three/addons/exporters/USDZExporter.js';
			
			// GUI：图形用户界面库，用于创建调试控制面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// ==================== 全局变量声明 ====================
			
			// Three.js核心对象声明（未初始化）
			// camera：相机，决定用户看到的3D场景视角
			// scene：场景，包含所有的3D对象（模型、灯光、相机等）
			// renderer：渲染器，负责将3D场景渲染到2D画布上
			let camera, scene, renderer;

			// GUI参数配置对象
			// 这个对象会被传递给GUI库，创建可交互的控制项
			const params = {
				// exportUSDZ是一个函数，当用户在GUI中点击时执行
				exportUSDZ: exportUSDZ
			};

			// ==================== 初始化入口 ====================
			
			// 调用初始化函数，设置Three.js环境
			init();
			// 调用渲染函数，第一次渲染场景
			render();

			// ==================== 函数定义区域 ====================
			
			/**
			 * 初始化函数 - 整个应用的启动入口
			 * 功能：
			 * 1. 创建并配置Three.js核心组件
			 * 2. 加载3D模型
			 * 3. 设置用户交互控制
			 * 4. 初始化USDZ导出功能
			 * 注意：这是一个无参数无返回值的函数
			 */
			function init() {
				// ---------- 1. 创建WebGL渲染器 ----------
				// new THREE.WebGLRenderer() 创建WebGL渲染器实例
				// { antialias: true } 配置选项，开启抗锯齿
				// 抗锯齿可以平滑3D模型的边缘，提高视觉质量
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				
				// 设置设备像素比，适配高DPI屏幕（如Retina显示屏）
				// window.devicePixelRatio获取设备的物理像素与CSS像素的比例
				// 设置这个值可以让渲染更清晰
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为整个窗口大小
				// window.innerWidth/innerHeight获取浏览器视口宽度和高度
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置色调映射算法
				// ACESFilmicToneMapping是一种电影级色调映射，提供更好的高光和阴影细节
				// 色调映射将HDR（高动态范围）颜色转换为显示器能显示的LDR（低动态范围）
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				
				// 将渲染器的canvas元素添加到网页body中
				// renderer.domElement是渲染器创建的<canvas>元素
				document.body.appendChild( renderer.domElement );

				// ---------- 2. 创建透视相机 ----------
				// new THREE.PerspectiveCamera() 创建透视相机实例
				// 参数说明：
				// 45 - 视野角度（FOV），单位度，类似人眼的视野范围
				// window.innerWidth / window.innerHeight - 纵横比，宽度除以高度
				// 0.25 - 近裁剪面，距离相机多近开始渲染
				// 20 - 远裁剪面，距离相机多远停止渲染
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 0.25, 20 );
				
				// 设置相机在3D空间中的位置
				// set(x, y, z) 设置三维坐标
				// x轴：左右方向（右为正）
				// y轴：上下方向（上为正）
				// z轴：前后方向（屏幕外向内为正）
				camera.position.set( - 2.5, 0.6, 3.0 );

				// ---------- 3. 创建环境光照 ----------
				// PMREMGenerator：预过滤的Mipmap辐射环境贴图生成器
				// 这是一种高级的环境光照技术，用于实时渲染
				// 它预计算环境贴图的不同Mipmap级别，提高渲染性能和质量
				const pmremGenerator = new THREE.PMREMGenerator( renderer );

				// ---------- 4. 创建场景 ----------
				// new THREE.Scene() 创建3D场景，所有3D对象的容器
				scene = new THREE.Scene();
				
				// 设置场景背景颜色
				// 0xf0f0f0是十六进制颜色值，浅灰色
				scene.background = new THREE.Color( 0xf0f0f0 );
				
				// 设置场景环境贴图
				// 先创建一个RoomEnvironment实例（预设的房间环境）
				// 然后使用PMREMGenerator将其转换为环境贴图
				// 0.04是环境贴图的强度参数
				scene.environment = pmremGenerator.fromScene( new RoomEnvironment(), 0.04 ).texture;

				// ---------- 5. 加载3D模型 ----------
				// 创建GLTFLoader实例并设置基础路径
				// setPath() 设置模型文件的基础路径
				const loader = new GLTFLoader().setPath( 'models/gltf/DamagedHelmet/glTF/' );
				
				// 加载GLTF模型文件
				// load() 方法异步加载模型
				// 参数1：模型文件名
				// 参数2：加载完成后的回调函数，接收加载的模型数据
				// async关键字表示这是一个异步函数，内部可以使用await
				loader.load( 'DamagedHelmet.gltf', async function ( gltf ) {
					// gltf参数包含加载的3D模型数据
					// gltf.scene是包含所有3D对象的场景图
					
					// 将加载的模型添加到主场景中
					scene.add( gltf.scene );

					// ---------- 6. 创建阴影平面 ----------
					// 调用createSpotShadowMesh()函数创建阴影效果
					const shadowMesh = createSpotShadowMesh();
					// 设置阴影位置
					shadowMesh.position.y = - 1.1;  // 向下移动1.1个单位
					shadowMesh.position.z = - 0.25; // 向后移动0.25个单位
					// 设置阴影缩放，setScalar(2)表示在所有轴上放大2倍
					shadowMesh.scale.setScalar( 2 );
					// 将阴影添加到场景
					scene.add( shadowMesh );

					// 渲染场景（此时模型已加载）
					render();

					// ---------- 7. USDZ导出处理 ----------
					// 创建USDZ导出器实例
					const exporter = new USDZExporter();
					
					// 异步解析场景为USDZ格式
					// parseAsync() 将Three.js场景转换为USDZ二进制数据
					// 只导出模型部分（gltf.scene），不包括阴影等其他元素
					// await等待解析完成，返回ArrayBuffer
					const arraybuffer = await exporter.parseAsync( gltf.scene );
					
					// 将ArrayBuffer转换为Blob对象
					// Blob表示二进制大对象，用于文件操作
					// 'application/octet-stream' 是通用的二进制MIME类型
					const blob = new Blob( [ arraybuffer ], { type: 'application/octet-stream' } );

					// 获取页面中的AR链接元素
					const link = document.getElementById( 'link' );
					// 创建Blob的URL并设置为链接的href
					// URL.createObjectURL() 创建指向Blob的临时URL
					link.href = URL.createObjectURL( blob );
					// 现在点击AR按钮就会下载USDZ文件

				} ); // GLTF加载回调函数结束

				// ---------- 8. 设置用户交互控制 ----------
				// 创建轨道控制器
				// OrbitControls将相机控制绑定到渲染器的canvas元素
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 添加变化事件监听器
				// 当用户交互改变相机位置时，触发render函数重新渲染
				controls.addEventListener( 'change', render );
				
				// 设置相机与目标点的最小距离（不能太近）
				controls.minDistance = 2;
				// 设置相机与目标点的最大距离（不能太远）
				controls.maxDistance = 10;
				// 设置控制器的目标点（相机围绕这个点旋转）
				controls.target.set( 0, - 0.15, - 0.2 );
				// 更新控制器内部状态
				controls.update();

				// ---------- 9. 窗口大小变化监听 ----------
				// 当浏览器窗口大小改变时，调用onWindowResize函数
				window.addEventListener( 'resize', onWindowResize );

				// ---------- 10. 设备检测和GUI设置 ----------
				// 检测是否为iOS设备（iPad、iPhone、iPod）
				// 使用正则表达式匹配用户代理字符串
				const isIOS = /iPad|iPhone|iPod/.test( navigator.userAgent );

				// 如果不是iOS设备，创建GUI控制面板
				// iOS设备通常有原生的AR查看方式，不需要额外的导出按钮
				if ( isIOS === false ) {
					// 创建GUI实例
					const gui = new GUI();
					
					// 添加控制项
					// gui.add(对象, 属性名) 将对象属性绑定到GUI控件
					// .name('Export USDZ') 设置控件显示名称
					gui.add( params, 'exportUSDZ' ).name( '导出USDZ文件' );
					
					// 默认打开GUI面板
					gui.open();
				}

			} // init函数结束

			/**
			 * 创建聚光灯阴影平面
			 * 功能：创建一个模拟聚光灯投影阴影的半透明平面
			 * 原理：使用Canvas绘制径向渐变纹理，然后应用到平面网格
			 * 这比真实动态阴影性能更好，适合静态场景
			 * 
			 * @returns {THREE.Mesh} 返回创建的阴影平面网格对象
			 * 包含几何体（平面）和材质（渐变纹理）
			 */
			function createSpotShadowMesh() {
				// ---------- 1. 创建Canvas元素 ----------
				// 创建HTML5 Canvas元素用于生成纹理
				const canvas = document.createElement( 'canvas' );
				// 设置Canvas尺寸为128x128像素
				// 这是纹理的分辨率，影响阴影的清晰度
				canvas.width = 128;
				canvas.height = 128;

				// ---------- 2. 获取2D绘图上下文 ----------
				const context = canvas.getContext( '2d' );
				
				// ---------- 3. 创建径向渐变 ----------
				// createRadialGradient() 创建圆形渐变
				// 参数说明：
				// x0, y0, r0 - 起始圆（内圆）的圆心和半径
				// x1, y1, r1 - 结束圆（外圆）的圆心和半径
				// 这里创建从中心点到边缘的渐变
				const gradient = context.createRadialGradient(
					canvas.width / 2,  // 中心点X坐标（Canvas宽度的一半）
					canvas.height / 2, // 中心点Y坐标（Canvas高度的一半）
					0,                  // 内圆半径（从中心开始）
					canvas.width / 2,  // 外圆圆心X坐标（与内圆相同）
					canvas.height / 2, // 外圆圆心Y坐标（与内圆相同）
					canvas.width / 2   // 外圆半径（扩展到Canvas边缘）
				);
				
				// 添加渐变颜色停止点
				// addColorStop(位置, 颜色)
				// 位置范围：0.0（起始点）到1.0（结束点）
				gradient.addColorStop( 0.1, 'rgba(130,130,130,1)' ); // 中心点：灰色，不透明
				gradient.addColorStop( 1, 'rgba(255,255,255,1)' );   // 边缘：白色，不透明
				// 实际效果：中心灰色，向外逐渐变白

				// ---------- 4. 绘制渐变 ----------
				// 设置填充样式为刚刚创建的渐变
				context.fillStyle = gradient;
				// 填充整个Canvas区域
				context.fillRect( 0, 0, canvas.width, canvas.height );

				// ---------- 5. 创建纹理 ----------
				// 将Canvas转换为Three.js纹理
				// CanvasTexture可以从Canvas元素创建纹理
				const shadowTexture = new THREE.CanvasTexture( canvas );

				// ---------- 6. 创建几何体 ----------
				// PlaneGeometry是平面几何体
				// 默认创建1x1单位的平面
				const geometry = new THREE.PlaneGeometry();

				// ---------- 7. 创建材质 ----------
				// MeshBasicMaterial是基础网格材质
				// 不受光照影响，直接显示颜色/纹理
				const material = new THREE.MeshBasicMaterial( {
					map: shadowTexture,           // 使用Canvas渐变纹理
					blending: THREE.MultiplyBlending, // 混合模式：正片叠底
					// MultiplyBlending将纹理颜色与背景颜色相乘
					// 产生变暗效果，适合阴影
					toneMapped: false,            // 禁用色调映射
					// 纹理有自己的颜色，不需要再进行色调映射
					premultipliedAlpha: true       // 启用预乘Alpha
					// 预乘Alpha可以提高透明纹理的渲染质量
				} );

				// ---------- 8. 创建网格 ----------
				// Mesh将几何体和材质组合成可渲染的3D对象
				const mesh = new THREE.Mesh( geometry, material );
				
				// 旋转平面，使其水平放置
				// 默认情况下，平面是垂直的（面向Z轴正方向）
				// 旋转-90度（-π/2弧度）使其变成水平面
				mesh.rotation.x = - Math.PI / 2;

				// 返回创建的阴影平面
				return mesh;
			} // createSpotShadowMesh函数结束

			/**
			 * 窗口大小变化处理函数
			 * 功能：当浏览器窗口大小改变时，调整Three.js渲染尺寸和相机参数
			 * 触发条件：用户调整浏览器窗口大小，或设备旋转（移动端）
			 * 这是响应式设计的关键部分
			 */
			function onWindowResize() {
				// ---------- 1. 更新相机纵横比 ----------
				// 窗口大小改变后，需要重新计算相机的宽高比
				// 否则渲染内容会被拉伸或压缩
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// updateProjectionMatrix() 重新计算相机如何将3D空间投影到2D屏幕
				// 这是必要的，因为改变了相机的aspect属性
				camera.updateProjectionMatrix();

				// ---------- 2. 更新渲染器尺寸 ----------
				// 将渲染器的canvas尺寸调整为新的窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );

				// ---------- 3. 重新渲染场景 ----------
				// 调用render函数，用新的尺寸重新绘制场景
				render();
			} // onWindowResize函数结束

			/**
			 * 导出USDZ文件
			 * 功能：触发USDZ文件的下载
			 * 在GUI中点击"导出USDZ文件"按钮时调用
			 * 实际上只是模拟点击AR链接元素
			 */
			function exportUSDZ() {
				// 获取页面中的AR链接元素
				const link = document.getElementById( 'link' );
				
				// 触发链接的点击事件
				// 这会触发浏览器下载USDZ文件（在init中已设置好链接）
				link.click();
				
				// 注意：在iOS设备上，这个链接有rel="ar"属性
				// iOS会自动识别并启动AR预览，而不是下载文件
			} // exportUSDZ函数结束

			/**
			 * 渲染函数
			 * 功能：执行实际的3D渲染
			 * 将场景和相机传递给渲染器，绘制到canvas上
			 * 这个函数可能被多次调用：
			 * 1. 初始化后
			 * 2. 模型加载完成后
			 * 3. 用户交互改变视角后
			 * 4. 窗口大小改变后
			 */
			function render() {
				// 调用渲染器的render方法
				// 参数1：要渲染的场景（包含所有3D对象）
				// 参数2：使用的相机（决定观察视角）
				renderer.render( scene, camera );
			} // render函数结束

		</script>
		<!-- 
			脚本结束
			整个应用逻辑都在这个模块中
			注意：ES6模块有自己作用域，这里定义的变量不会污染全局作用域
		-->
	</body>
	<!-- 
		页面结束
		整个HTML文档结构完成
	-->
</html>