<!-- 代码功能概述
这是一个基于 Three.js WebGPU 版本 的 骨骼动画重定向（Animation Retargeting） 技术演示。该应用将 Mixamo 平台 的角色动画数据实时应用到 ReadyPlayer.me 平台 的角色模型上，展示了跨平台、跨模型的动画适配技术。

核心功能
动画重定向：将源角色（Mixamo）的动画数据映射到目标角色（ReadyPlayer.me）的骨骼系统

双模型对比展示：并排显示源模型和目标模型，直观展示重定向效果

实时动画播放：流畅播放重定向后的角色动画

交互式3D查看：支持用户旋转、缩放视角，多角度观察模型

现代3D渲染：采用WebGPU渲染器，实现高质量的视觉特效

主要技术点详解
1. WebGPU 渲染技术
javascript
const renderer = new THREE.WebGPURenderer({ antialias: true });
技术优势：相比传统的WebGL，WebGPU提供更好的性能和更现代的GPU API

功能特性：

支持计算着色器和高级GPU功能

更好的多线程支持

更高效的资源管理

2. 骨骼动画重定向核心算法
javascript
const retargetedClip = SkeletonUtils.retargetClip(
  targetSkin,           // 目标蒙皮网格
  sourceModel.skeleton, // 源骨骼系统
  sourceModel.clip,     // 源动画片段
  retargetOptions       // 重定向参数配置
);
重定向过程包含：
骨骼映射：通过命名约定匹配源骨骼和目标骨骼

比例适配：解决不同模型的尺寸差异（Mixamo用厘米，Three.js用米）

坐标系转换：处理不同模型的骨骼局部坐标系

动画数据插值：确保动画平滑过渡

关键配置参数：
javascript
const retargetOptions = {
  hip: 'mixamorigHips',              // 根骨骼名称
  scale: 0.01,                       // 比例缩放因子
  getBoneName: (bone) => 'mixamorig' + bone.name // 骨骼名称映射函数
};
3. 节点着色器系统（TSL - Three.js Shading Language）
javascript
import { screenUV, color, vec2, reflector } from 'three/tsl';
主要应用：
动态背景生成

javascript
const horizontalEffect = screenUV.x.mix(color(0x13172b), color(0x311649));
创建水平渐变的背景颜色

实现基于屏幕坐标的颜色插值

地板反射效果

javascript
const reflection = reflector();
const reflectionMask = positionWorld.xz.distance(0).mul(0.1).clamp().oneMinus();
使用反射器节点创建实时反射

通过距离计算反射衰减遮罩

实现距离越远反射越弱的效果

4. 多格式模型加载系统
javascript
// 并行加载FBX和GLB格式模型
const [sourceModel, targetModel] = await Promise.all([
  new FBXLoader().load('./models/fbx/mixamo.fbx'),
  new GLTFLoader().load('./models/gltf/readyplayer.me.glb')
]);
FBX格式：包含Mixamo的完整动画数据

GLB格式：ReadyPlayer.me的骨骼模型

并行加载：使用Promise.all优化加载性能

5. 光照系统配置
javascript
// 三种灯光组合创建逼真光照
const hemisphereLight = new THREE.HemisphereLight(0x311649, 0x0c5d68, 10); // 环境光
const backLight = new THREE.DirectionalLight(0xffffff, 10); // 轮廓光
const keyLight = new THREE.DirectionalLight(0xfff9ea, 4);   // 主光源
半球光：模拟天空和地面的环境反射

背光：增强角色轮廓分离度

主光：提供主要的照明和阴影

6. 单位转换与比例调整
javascript
// Mixamo使用厘米单位，Three.js使用米单位
sourceModel.scale.setScalar(0.01); // 缩小100倍
问题：不同3D建模软件使用不同的单位系统

解决方案：统一缩放到Three.js的米制系统

重要性：确保动画在正确的尺度上播放

7. 动画系统架构
javascript
// 创建动画混合器管理动画状态
const mixer = new THREE.AnimationMixer(targetSkin);
mixer.clipAction(retargetedClip).play();

// 每帧更新动画
function animate() {
  const delta = clock.getDelta(); // 基于时间差的更新
  mixer.update(delta);
}
基于时间的动画更新：使用clock.getDelta()确保动画速度与帧率无关

动画混合器：管理多个动画状态和过渡

8. 交互控制系统
javascript
const controls = new OrbitControls(camera, renderer.domElement);
controls.minDistance = 3;
controls.maxDistance = 12;
controls.maxPolarAngle = Math.PI / 2; // 限制垂直旋转角度
轨道控制：支持鼠标拖拽旋转和滚轮缩放

使用限制：防止用户进入不合理的视角

9. 响应式设计
javascript
window.onresize = function() {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
};
自适应窗口大小：自动调整渲染分辨率和摄像机参数

保持视觉比例：正确更新投影矩阵

技术难点与解决方案
难点1：骨骼名称不匹配
问题：Mixamo和ReadyPlayer.me使用不同的骨骼命名约定

解决方案：通过getBoneName函数实现名称映射

javascript
getBoneName: function(bone) {
  return 'mixamorig' + bone.name; // 添加Mixamo前缀
}
难点2：骨骼层级差异
问题：不同模型的骨骼层级结构不同

解决方案：Three.js的SkeletonUtils自动处理层级映射和变换计算

难点3：动画比例不一致
问题：不同角色的骨骼长度和比例不同

解决方案：通过缩放因子和髋骨影响参数调整动画幅度

应用场景
游戏开发：将标准动画库应用到自定义角色模型

虚拟人/数字人：在不同虚拟形象间复用高质量动画

影视动画：提高动画制作效率，实现动画资产的复用

元宇宙应用：支持用户自定义角色的丰富动画表现

性能优化特点
WebGPU优势：更好的并行处理能力和内存管理

并行加载：同时加载多个模型减少等待时间

基于时间的动画：确保不同刷新率设备上的动画一致性

着色器优化：使用TSL节点实现高效的GPU计算 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面元数据设置：
			- title标签：定义浏览器标签页标题，对SEO友好
			- charset：使用UTF-8编码支持中文字符
			- viewport：设置移动端自适应，禁止用户手动缩放
		-->
		<title>Three.js WebGPU - 动画重定向技术演示</title>
		<meta charset="utf-8">
		<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"：为div元素指定唯一标识，便于CSS和JS操作
			- 包含Three.js链接、标题和功能说明
		-->
		<div id="info">
			<!-- 
				Three.js官网链接：
				- target="_blank"：在新标签页打开链接
				- rel="noopener"：安全属性，防止新页面访问原始页面的window.opener属性
				- class="logo-link"：CSS类名，通常用于添加Three.js的logo背景图
			-->
			<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>
				<!-- 
					功能描述：
					- 将Mixamo平台的动画数据重定向到ReadyPlayer.me角色模型
					- 这是一个在3D动画和游戏开发中常用的技术
				-->
				本示例演示如何将 <a href="https://www.mixamo.com/" target="_blank" rel="noopener">Mixamo</a> 
				平台的角色动画数据重定向到 
				<a href="https://readyplayer.me/" target="_blank" rel="noopener">ReadyPlayer.me</a> 
				角色模型上。
				<br>
				<!-- 补充说明，解释技术应用的场景 -->
				<em>动画重定向技术广泛应用于游戏开发、虚拟角色动画和影视制作领域。</em>
			</small>
		</div>

		<!-- 
			Import Maps（导入映射表）：
			- 现代浏览器支持的模块解析功能
			- 定义JavaScript模块的导入路径别名
			- 避免在代码中直接写相对路径，提高可维护性
			- 使浏览器能够正确解析ES模块的导入语句
		-->
		<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语法
			- 所有代码将在模块作用域内执行
		-->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js的核心功能和WebGPU渲染器
			import * as THREE from 'three/webgpu';
			
			// 导入Three.js着色器语言（TSL）的节点函数
			// screenUV: 屏幕UV坐标（0到1范围）
			// color: 创建颜色节点
			// vec2/vec4: 创建2维/4维向量节点
			// reflector: 创建反射器节点
			// positionWorld: 世界坐标系位置节点
			import { screenUV, color, vec2, vec4, reflector, positionWorld } from 'three/tsl';

			// 导入Three.js的附加组件（插件）
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';  // 轨道摄像机控制器
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';        // GLTF格式模型加载器
			import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';          // FBX格式模型加载器
			import { Inspector } from 'three/addons/inspector/Inspector.js';        // 3D场景调试检查器

			// 导入骨骼工具集，包含动画重定向的核心功能
			import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';

			// ==================== 模型加载区域 ====================
			// 使用Promise.all并行加载两个3D模型，提高加载效率
			// sourceModel: 源模型（带动画的Mixamo角色）
			// targetModel: 目标模型（需要接收动画的ReadyPlayer.me角色）
			const [ sourceModel, targetModel ] = await Promise.all( [

				// 加载FBX格式的Mixamo模型
				new Promise( ( resolve, reject ) => {
					// 创建FBX加载器实例
					const loader = new FBXLoader();
					// 异步加载模型文件
					loader.load( 
						'./models/fbx/mixamo.fbx', // 模型文件路径
						resolve,                    // 加载成功回调
						undefined,                  // 加载进度回调（这里未使用）
						reject                      // 加载失败回调
					);
				} ),

				// 加载GLB格式的ReadyPlayer.me模型
				new Promise( ( resolve, reject ) => {
					// 创建GLTF加载器实例
					const loader = new GLTFLoader();
					// 异步加载模型文件
					loader.load( 
						'./models/gltf/readyplayer.me.glb', // 模型文件路径
						resolve,                            // 加载成功回调
						undefined,                          // 加载进度回调
						reject                              // 加载失败回调
					);
				} )

			] );

			// ==================== 核心对象初始化 ====================
			// 创建Three.js时钟对象，用于计算动画帧之间的时间差
			const clock = new THREE.Clock();

			// 创建3D场景容器，所有3D对象都将添加到场景中
			const scene = new THREE.Scene();

			// ==================== 场景背景设置 ====================
			// 使用TSL节点着色器创建动态背景效果
			// horizontalEffect: 水平渐变效果（从左到右的颜色过渡）
			const horizontalEffect = screenUV.x.mix( 
				color( 0x13172b ), // 左侧颜色（深蓝色）
				color( 0x311649 )  // 右侧颜色（深紫色）
			);
			
			// lightEffect: 中心光源效果（从屏幕中心向外衰减）
			const lightEffect = screenUV
				.distance( vec2( 0.5, 1.0 ) )  // 计算每个像素到点(0.5, 1.0)的距离
				.oneMinus()                     // 反转距离值（中心点值最大）
				.mul( color( 0x0c5d68 ) );      // 乘以颜色值（青蓝色）
			
			// 将两个效果叠加，设置为场景背景
			scene.backgroundNode = horizontalEffect.add( lightEffect );

			// ==================== 灯光系统设置 ====================
			// 1. 半球光：模拟自然光照（天空光和地面反射光）
			const hemisphereLight = new THREE.HemisphereLight( 
				0x311649, // 天空颜色（深紫色）
				0x0c5d68, // 地面颜色（青蓝色）
				10        // 光照强度
			);
			scene.add( hemisphereLight );

			// 2. 背光：从后方照亮物体，增强轮廓感
			const backLight = new THREE.DirectionalLight( 0xffffff, 10 );
			backLight.position.set( 0, 5, -5 );  // 设置在物体的后上方
			scene.add( backLight );

			// 3. 主光（关键光）：主要光源，提供主要的照明和阴影
			const keyLight = new THREE.DirectionalLight( 0xfff9ea, 4 );
			keyLight.position.set( 3, 5, 3 );  // 设置在物体的右前上方
			scene.add( keyLight );

			// ==================== 摄像机设置 ====================
			// 创建透视摄像机（模拟人眼视角）
			const camera = new THREE.PerspectiveCamera( 
				40,                              // 视场角（FOV），单位：度
				window.innerWidth / window.innerHeight, // 宽高比
				0.25,                            // 近裁剪面（距离小于此值的不渲染）
				50                               // 远裁剪面（距离大于此值的不渲染）
			);
			camera.position.set( 0, 3, 5 );  // 设置摄像机初始位置

			// ==================== 模型处理 ====================
			// 将加载的模型添加到场景中
			scene.add( sourceModel );          // 添加源模型（Mixamo）
			scene.add( targetModel.scene );    // 添加目标模型（ReadyPlayer.me）

			// 调整模型位置，使两个模型并排显示
			sourceModel.position.x -= 0.9;      // 源模型向左移动0.9单位
			targetModel.scene.position.x += 0.9; // 目标模型向右移动0.9单位

			// 调整源模型的比例
			// Mixamo模型使用厘米为单位，Three.js默认使用米为单位
			// 需要将Mixamo模型缩小100倍（0.01 = 1/100）
			sourceModel.scale.setScalar( 0.01 );

			// ==================== 动画重定向核心逻辑 ====================
			// 获取源模型的动画数据（骨骼、动画片段等）
			const source = getSource( sourceModel );
			// 执行动画重定向：将源模型的动画应用到目标模型
			const mixer = retargetModel( source, targetModel );

			// ==================== 渲染器设置 ====================
			// 创建WebGPU渲染器（Three.js的最新渲染器，性能优于WebGL）
			const renderer = new THREE.WebGPURenderer( { 
				antialias: true  // 开启抗锯齿，使边缘更平滑
			} );
			renderer.setPixelRatio( window.devicePixelRatio );  // 适配高清显示屏
			renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
			renderer.setAnimationLoop( animate );  // 设置动画循环回调函数
			renderer.inspector = new Inspector();  // 附加调试检查器（按F12可调出）
			renderer.toneMapping = THREE.NeutralToneMapping;  // 设置色调映射算法
			document.body.appendChild( renderer.domElement );  // 将canvas元素添加到页面

			// ==================== 交互控制设置 ====================
			// 创建轨道控制器，实现鼠标拖拽旋转和滚轮缩放
			const controls = new OrbitControls( camera, renderer.domElement );
			controls.minDistance = 3;     // 最小缩放距离（摄像机不能更靠近目标）
			controls.maxDistance = 12;    // 最大缩放距离（摄像机不能更远离目标）
			controls.target.set( 0, 1, 0 );  // 设置控制器的焦点位置（模型的大致中心）
			controls.maxPolarAngle = Math.PI / 2;  // 限制垂直旋转角度（防止摄像机翻转到模型下方）

			// ==================== 场景装饰元素 ====================
			// 创建反射效果（用于模拟地板反射）
			const reflection = reflector();  // 创建反射器节点
			reflection.target.rotateX( -Math.PI / 2 );  // 将反射器旋转90度（面向摄像机）
			scene.add( reflection.target );

			// 创建反射遮罩：控制反射效果的衰减
			// 根据像素到原点的距离计算遮罩值，距离越远反射越弱
			const reflectionMask = positionWorld.xz          // 获取世界坐标的XZ平面分量
				.distance( 0 )                               // 计算到原点(0,0)的距离
				.mul( 0.1 )                                  // 乘以0.1调整衰减速度
				.clamp()                                     // 将值限制在0-1范围
				.oneMinus();                                 // 反转值（中心点反射最强）

			// 创建地板材质（使用节点材质系统）
			const floorMaterial = new THREE.NodeMaterial();
			// 设置材质颜色节点：反射颜色 + 透明度遮罩
			floorMaterial.colorNode = vec4( reflection.rgb, reflectionMask );
			floorMaterial.opacity = 0.2;      // 设置材质整体透明度
			floorMaterial.transparent = true; // 启用透明度

			// 创建地板网格对象
			const floor = new THREE.Mesh( 
				new THREE.BoxGeometry( 50, 0.001, 50 ), // 创建50x50的扁平立方体作为地板
				floorMaterial                           // 应用刚才创建的地板材质
			);
			floor.receiveShadow = true;  // 允许地板接收阴影
			floor.position.set( 0, 0, 0 );  // 将地板放置在场景中心
			scene.add( floor );

			// ==================== 工具函数定义 ====================

			/**
			 * 提取源模型的动画数据
			 * 该函数从Mixamo模型中提取动画片段、骨骼结构和动画混合器
			 * 
			 * @param {THREE.Object3D} sourceModel - 源3D模型对象（Mixamo模型）
			 * @returns {Object} 包含以下属性的对象：
			 *   - clip: THREE.AnimationClip 动画片段（包含关键帧数据）
			 *   - skeleton: THREE.Skeleton 骨骼结构（描述骨骼层级和变换）
			 *   - mixer: THREE.AnimationMixer 动画混合器（用于播放和控制动画）
			 */
			function getSource( sourceModel ) {
				// 获取模型中的第一个动画片段（Mixamo模型通常只包含一个动画）
				const clip = sourceModel.animations[ 0 ];

				// 创建骨骼辅助器来分析模型的骨骼结构
				// SkeletonHelper会遍历模型的所有骨骼，并可视化显示骨骼连接
				const helper = new THREE.SkeletonHelper( sourceModel );
				// 从辅助器中提取骨骼数组，创建正式的骨骼对象
				const skeleton = new THREE.Skeleton( helper.bones );

				// 创建动画混合器，用于管理和播放动画
				const mixer = new THREE.AnimationMixer( sourceModel );
				// 创建动画动作并立即播放
				mixer.clipAction( sourceModel.animations[ 0 ] ).play();

				// 返回封装好的动画数据
				return { clip, skeleton, mixer };
			}

			/**
			 * 执行动画重定向的核心函数
			 * 将源模型（Mixamo）的动画数据应用到目标模型（ReadyPlayer.me）上
			 * 
			 * @param {Object} sourceModel - 源模型数据对象（来自getSource函数）
			 * @param {Object} targetModel - 目标模型数据（GLTF加载器返回的对象）
			 * @returns {THREE.AnimationMixer} 目标模型的动画混合器
			 */
			function retargetModel( sourceModel, targetModel ) {
				// 获取目标模型的蒙皮网格对象
				// 假设目标模型的结构为：scene -> group -> skinnedMesh
				const targetSkin = targetModel.scene.children[ 0 ].children[ 1 ];

				// 配置动画重定向的选项参数
				const retargetOptions = {
					// 指定源模型中的髋骨名称（动画通常以髋骨为根节点）
					hip: 'mixamorigHips',
					
					// 缩放比例：保持目标模型的原始比例
					// 由于源模型已经缩放过，这里需要相应的补偿
					scale: 0.01,
					
					// 髋骨移动影响范围（可选，当前被注释）
					// 可以限制髋骨动画在哪些轴向上影响目标模型
					// 例如 new THREE.Vector3(0, 1, 0) 表示只影响Y轴（垂直方向）
					// hipInfluence: new THREE.Vector3(0, 1, 0),
					
					/**
					 * 骨骼名称映射函数
					 * 将目标模型的骨骼名称映射到源模型的对应骨骼名称
					 * 
					 * @param {THREE.Bone} bone - 目标模型的骨骼对象
					 * @returns {string} 源模型中对应的骨骼名称
					 */
					getBoneName: function ( bone ) {
						// Mixamo的骨骼命名约定：在原始骨骼名前添加"mixamorig"前缀
						return 'mixamorig' + bone.name;
					}
				};

				/**
				 * 执行动画重定向的核心调用
				 * SkeletonUtils.retargetClip函数会：
				 * 1. 分析源模型的动画关键帧数据
				 * 2. 根据骨骼映射关系找到对应的目标骨骼
				 * 3. 将动画数据适配到目标骨骼的比例和初始姿势
				 * 4. 生成一个新的动画片段
				 */
				const retargetedClip = SkeletonUtils.retargetClip( 
					targetSkin,          // 目标蒙皮网格
					sourceModel.skeleton, // 源模型的骨骼结构
					sourceModel.clip,     // 源模型的动画片段
					retargetOptions       // 重定向配置
				);

				// 为目标模型创建动画混合器
				const mixer = new THREE.AnimationMixer( targetSkin );
				// 创建并播放重定向后的动画动作
				mixer.clipAction( retargetedClip ).play();

				// 返回混合器，便于后续的动画控制
				return mixer;
			}

			// ==================== 事件处理函数 ====================

			/**
			 * 窗口大小调整事件处理函数
			 * 当浏览器窗口大小改变时，调整摄像机和渲染器的设置
			 */
			window.onresize = function () {
				// 更新摄像机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 必须调用updateProjectionMatrix()使新的宽高比生效
				camera.updateProjectionMatrix();
				// 更新渲染器的尺寸以匹配新窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
			};

			/**
			 * 动画循环函数
			 * 这是Three.js应用的核心循环，每帧都会被调用（通常每秒60次）
			 * 负责更新动画状态、控制器状态并重新渲染场景
			 */
			function animate() {
				// 获取上一帧到当前帧的时间差（秒）
				// 使用时间差而非固定帧率，确保动画在不同刷新率的显示器上速度一致
				const delta = clock.getDelta();

				// 更新所有动画混合器
				// 传入时间差，使动画按正确速度播放
				source.mixer.update( delta );  // 更新源模型的动画（参考动画）
				mixer.update( delta );         // 更新目标模型的动画（重定向后的动画）

				// 更新轨道控制器状态（处理鼠标/触摸输入）
				controls.update();

				// 渲染场景：将3D场景通过摄像机视角绘制到canvas上
				renderer.render( scene, camera );
			}

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