<!-- Three.js SVG 三维场景演示项目详解
一、项目核心功能概述
这是一个使用 Three.js SVG 渲染器 创建的交互式3D图形演示应用，主要功能包括：

1. 3D场景渲染与交互
将复杂的3D几何图形实时渲染为SVG矢量格式

提供完整的鼠标/触摸交互控制（旋转、缩放、平移）

支持响应式布局，自动适应不同屏幕尺寸

2. 多样化的3D对象展示
几何体集合：立方体、圆柱体、平面等基础形状

动态三角形场：100个随机生成、持续旋转的彩色三角形

2D精灵系统：50个始终面向相机的2D图像元素

SVG集成：原生SVG元素与3D场景的深度融合

外部资源加载：QR码模型和六边形SVG文件

3. 视觉与性能特性
矢量图形优势：无限缩放不失真，适合高分辨率输出

光照系统：环境光+定向光的组合照明

动画效果：平滑的旋转动画和实时渲染

性能监控：内置帧率显示和性能统计

二、主要技术架构
1. Three.js 核心模块
javascript
// 核心渲染管线
Three.js 3D引擎 → SVGRenderer → SVG矢量输出

// 关键模块
- Scene（场景管理）
- Camera（视角控制）
- Geometry/Mesh（几何体与网格）
- Material（材质系统）
- Lights（光照系统）
2. SVG 渲染技术栈
text
技术栈层次：
1. HTML5 + CSS3（页面结构）
2. ES6 Modules（模块化管理）
3. Three.js Core（3D引擎）
4. SVG Renderer（矢量渲染）
5. DOM API（SVG操作）
三、关键技术点详解
1. SVG矢量渲染器 (SVGRenderer)
javascript
// 独特优势
- 基于数学公式而非像素的渲染
- 输出可编辑的SVG矢量图形
- 支持CSS样式和DOM操作
- 适合打印和高DPI设备

// 性能权衡
+ 优点：无限缩放、文件较小、易于编辑
- 缺点：复杂场景性能较低、动画限制多
2. 三维几何系统
javascript
// 三种几何创建方式
1. 内置几何体：BoxGeometry, CylinderGeometry等
2. 自定义BufferGeometry：高效顶点数据处理
3. 文件加载：JSON格式的预定义几何数据

// 顶点数据处理示例
geometry.setAttribute('position', Float32BufferAttribute)  // 位置
geometry.setAttribute('color', Float32BufferAttribute)     // 颜色
3. 材质与着色系统
javascript
// 材质类型
- MeshBasicMaterial：基础材质（不受光照影响）
- MeshLambertMaterial：朗伯材质（漫反射）
- SpriteMaterial：精灵材质（始终面向相机）

// 颜色系统
- 顶点颜色：每个顶点独立颜色（三角形场使用）
- 材质颜色：整个物体统一颜色
- 随机生成：Math.random() * 0xffffff
4. 相机与控制器系统
javascript
// 透视相机配置
new PerspectiveCamera(75, aspect, 1, 10000)
参数说明：
- 75°：垂直视场角（FOV）
- aspect：宽高比（自适应屏幕）
- 1：近裁剪平面
- 10000：远裁剪平面

// 轨道控制器功能
- 左键拖动：绕场景中心旋转
- 右键拖动：平移场景
- 滚轮：缩放视图
- 触摸支持：移动端适配
5. 动画与性能优化
javascript
// 动画循环机制
function animate() {
    requestAnimationFrame(animate);  // 浏览器优化调用
    render();                         // 渲染逻辑
    stats.update();                   // 性能监控
}

// 性能监控
Stats.js 显示：
- FPS：每秒帧数（目标60fps）
- MS：每帧渲染时间（毫秒）
- MB：内存使用情况
四、核心代码模块分析
1. 初始化模块 (init函数)
javascript
// 执行顺序
1. 创建相机和场景容器
2. 加载外部资源（QR码、SVG文件）
3. 创建各类3D对象
4. 设置灯光系统
5. 初始化渲染器和控制器
6. 绑定事件监听器
2. 几何生成模块
javascript
// 三角形场生成算法
for (循环100次) {
    1. 生成随机中心位置
    2. 创建三个随机偏移向量
    3. 计算顶点最终位置
    4. 分配随机颜色
    5. 添加到顶点和颜色数组
}

// 结果：100个位置、颜色各异的三角形
3. SVG集成模块
javascript
// SVG与3D场景的三种集成方式
1. SVGObject包装：将DOM SVG元素转为3D对象
2. 动态创建：createElementNS创建SVG元素
3. 文件加载：FileLoader + DOMParser解析SVG文件
4. 响应式处理模块
javascript
// 窗口大小变化处理
window.addEventListener('resize', () => {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();  // 更新相机矩阵
    renderer.setSize(...);             // 更新渲染器尺寸
}); -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面元信息 -->
		<!-- 页面标题：Three.js SVG 三维场景演示 -->
		<title>Three.js SVG 三维场景演示 - 矢量图形渲染沙箱</title>
		<!-- 设置文档字符编码为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 
			视口(viewport)设置：
			width=device-width - 宽度等于设备宽度
			user-scalable=no - 禁止用户缩放（为3D场景优化）
			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="main.css">
		<!-- 内联CSS样式 -->
		<style>
			/* 确保所有SVG元素以块级元素显示，避免布局问题 */
			svg {
				display: block;
			}
			/* 信息面板样式 */
			#info {
				position: absolute;
				top: 10px;
				left: 10px;
				background-color: rgba(255, 255, 255, 0.8);
				padding: 15px;
				border-radius: 5px;
				font-family: "Microsoft YaHei", sans-serif;
				font-size: 14px;
				max-width: 300px;
				box-shadow: 0 2px 10px rgba(0,0,0,0.1);
			}
			#info h2 {
				margin-top: 0;
				color: #333;
			}
			#info ul {
				padding-left: 20px;
			}
			#info li {
				margin-bottom: 5px;
			}
		</style>
	</head>
	<body>
		<!-- 信息显示面板 -->
		<div id="info">
			<h2>Three.js SVG 渲染演示</h2>
			<p style="color: black;"><strong>场景说明：</strong>本示例使用Three.js的SVG渲染器将3D场景渲染为矢量图形。</p>
		</div>

		<!-- 
			导入映射(Import Map)：
			定义JavaScript模块的路径别名，用于模块化导入
			这是现代浏览器支持的模块解析机制
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module"表示这是一个ES6模块，支持模块化导入导出
			模块中的代码在严格模式下运行，作用域独立
		-->
		<script type="module">

			// 导入Three.js核心库的所有功能
			// Three.js是一个强大的3D图形库，用于创建和显示3D计算机图形
			import * as THREE from 'three';

			// 导入性能监视器(Stats.js)
			// 这是一个显示帧率(FPS)、渲染时间等性能指标的小工具
			import Stats from 'three/addons/libs/stats.module.js';
			
			// 导入轨道控制器(OrbitControls)
			// 允许用户通过鼠标/触摸屏控制相机视角，实现旋转、平移、缩放等功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// 导入SVG渲染器和SVG对象类
			// SVGRenderer：将3D场景渲染为SVG矢量图形的渲染器
			// SVGObject：可以在Three.js场景中使用的SVG元素对象
			import { SVGRenderer, SVGObject } from 'three/addons/renderers/SVGRenderer.js';

			// 禁用Three.js的颜色管理系统
			// 这是一个兼容性设置，旧版本Three.js可能不需要颜色管理
			// 颜色管理系统用于在不同颜色空间之间正确转换颜色
			THREE.ColorManagement.enabled = false;

			// 全局变量声明
			// camera：场景相机，定义观察者的视角
			// scene：场景容器，包含所有3D对象
			// renderer：渲染器，负责将3D场景渲染到2D屏幕
			// stats：性能监视器实例
			// controls：轨道控制器实例
			let camera, scene, renderer, stats, controls;

			// group：用于存储和操作三角形组的引用
			// 这个组包含100个随机生成的彩色三角形
			let group;

			// 初始化函数调用 - 程序入口点
			// 这个函数设置场景、相机、渲染器和所有3D对象
			init();
			
			// 启动动画循环
			// 这个函数持续调用自身，创建动画效果
			animate();

			/**
			 * 初始化函数
			 * 这是整个应用程序的初始化入口点
			 * 负责创建场景、相机、渲染器、3D对象、灯光等所有必要组件
			 * 并设置事件监听器
			 */
			function init() {

				// =================== 相机设置 ===================
				// 创建透视相机(PerspectiveCamera)
				// 参数说明：
				// 75 - 视场角(Field of View)，单位度，控制视角宽度
				// window.innerWidth / window.innerHeight - 纵横比，确保渲染比例正确
				// 1 - 近裁剪平面，距离相机小于此值的物体不被渲染
				// 10000 - 远裁剪平面，距离相机大于此值的物体不被渲染
				camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 1, 10000);
				// 设置相机初始位置：沿Z轴正方向移动500个单位
				// 在Three.js中，默认情况下Z轴垂直于屏幕，正方向指向屏幕外
				camera.position.z = 500;

				// =================== 场景设置 ===================
				// 创建场景对象
				// 场景是所有3D对象的容器，包括网格、灯光、相机等
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色（十六进制颜色码0xf0f0f0）
				// 背景色会在渲染时填充没有物体的区域
				scene.background = new THREE.Color(0xf0f0f0);

				// =================== QR码模型加载 ===================
				// 创建BufferGeometryLoader实例
				// BufferGeometry是Three.js中高效存储几何数据的格式
				const loader = new THREE.BufferGeometryLoader();
				
				// 异步加载QR码的几何数据JSON文件
				// 回调函数在文件加载完成后执行
				loader.load('models/json/QRCode_buffergeometry.json', function (geometry) {
					// 使用加载的几何体和材质创建网格对象
					// MeshLambertMaterial是一种对光照有反应的材质，用于创建哑光表面
					// vertexColors: true 表示使用顶点颜色数据（如果几何体包含）
					mesh = new THREE.Mesh(geometry, new THREE.MeshLambertMaterial({ vertexColors: true }));
					
					// 统一缩放网格：将QR码放大2倍
					// scale.x、scale.y、scale.z分别控制三个轴向上的缩放
					mesh.scale.x = mesh.scale.y = mesh.scale.z = 2;
					
					// 将创建的网格对象添加到场景中
					scene.add(mesh);
				});

				// =================== 创建立方体对象 ===================
				// 创建立方体几何体，参数：宽100、高100、深100
				const boxGeometry = new THREE.BoxGeometry(100, 100, 100);

				// 第一个立方体：半透明蓝色
				// 使用MeshBasicMaterial基础材质，不受光照影响
				let mesh = new THREE.Mesh(boxGeometry, new THREE.MeshBasicMaterial({ 
					color: 0x0000ff,      // 蓝色（十六进制颜色）
					opacity: 0.5,          // 不透明度50%
					transparent: true      // 启用透明度
				}));
				mesh.position.x = 500;           // 沿X轴正方向移动500单位
				mesh.rotation.x = Math.random(); // 随机X轴旋转角度
				mesh.rotation.y = Math.random(); // 随机Y轴旋转角度
				mesh.scale.x = mesh.scale.y = mesh.scale.z = 2; // 统一放大2倍
				scene.add(mesh);                 // 添加到场景

				// 第二个立方体：随机颜色
				// 使用随机生成的十六进制颜色
				mesh = new THREE.Mesh(boxGeometry, new THREE.MeshBasicMaterial({ 
					color: Math.random() * 0xffffff // 0xffffff是白色，乘以随机数得到随机颜色
				}));
				mesh.position.x = 500;           // X轴位置500
				mesh.position.y = 500;           // Y轴位置500（在第一个立方体上方）
				mesh.rotation.x = Math.random(); // 随机旋转
				mesh.rotation.y = Math.random();
				mesh.scale.x = mesh.scale.y = mesh.scale.z = 2; // 放大2倍
				scene.add(mesh);                 // 添加到场景

				// =================== 创建平面对象 ===================
				// 创建平面几何体，参数：宽100、高100
				mesh = new THREE.Mesh(
					new THREE.PlaneGeometry(100, 100), 
					new THREE.MeshBasicMaterial({ 
						color: Math.random() * 0xffffff, // 随机颜色
						side: THREE.DoubleSide  // 双面渲染，平面两面都显示材质
					})
				);
				mesh.position.y = -500;  // 沿Y轴负方向移动500单位
				mesh.scale.x = mesh.scale.y = mesh.scale.z = 2; // 放大2倍
				scene.add(mesh);         // 添加到场景

				// =================== 创建圆柱体对象 ===================
				// 创建圆柱体几何体，参数：
				// 20 - 顶部半径
				// 100 - 底部半径
				// 200 - 高度
				// 10 - 径向分段数（圆滑程度）
				mesh = new THREE.Mesh(
					new THREE.CylinderGeometry(20, 100, 200, 10),
					new THREE.MeshBasicMaterial({ color: Math.random() * 0xffffff })
				);
				mesh.position.x = -500;             // 沿X轴负方向移动500单位
				mesh.rotation.x = -Math.PI / 2;     // 绕X轴旋转-90度（使圆柱体水平放置）
				mesh.scale.x = mesh.scale.y = mesh.scale.z = 2; // 放大2倍
				scene.add(mesh);                    // 添加到场景

				// =================== 创建三角形场（自定义几何体） ===================
				// 创建BufferGeometry实例
				// BufferGeometry是Three.js中用于存储几何数据的高效格式
				const geometry = new THREE.BufferGeometry();
				
				// 创建基础材质，使用顶点颜色，双面渲染
				const material = new THREE.MeshBasicMaterial({ 
					vertexColors: true,   // 启用顶点颜色（每个顶点可以有独立颜色）
					side: THREE.DoubleSide // 双面渲染
				});

				// 辅助向量变量声明
				// 这些变量用于临时存储向量数据，避免重复创建对象
				const v = new THREE.Vector3();   // 基础位置向量
				const v0 = new THREE.Vector3();  // 三角形第一个顶点
				const v1 = new THREE.Vector3();  // 三角形第二个顶点
				const v2 = new THREE.Vector3();  // 三角形第三个顶点
				const color = new THREE.Color(); // 颜色对象

				// 数组声明
				const vertices = [];  // 顶点位置数组：存储所有三角形的顶点坐标 [x1, y1, z1, x2, y2, z2, ...]
				const colors = [];    // 顶点颜色数组：存储每个顶点对应的颜色值 [r1, g1, b1, r2, g2, b2, ...]

				// 循环创建100个随机三角形
				for (let i = 0; i < 100; i++) {
					// 生成三角形的基础位置（每个三角形组的中心点）
					v.set(
						Math.random() * 1000 - 500,  // X坐标：-500到500之间随机
						Math.random() * 1000 - 500,  // Y坐标：-500到500之间随机
						Math.random() * 1000 - 500   // Z坐标：-500到500之间随机
					);

					// 生成三个偏移向量（相对于基础位置）
					v0.set(
						Math.random() * 100 - 50,    // X偏移：-50到50之间随机
						Math.random() * 100 - 50,    // Y偏移：-50到50之间随机
						Math.random() * 100 - 50     // Z偏移：-50到50之间随机
					);
					v1.set(
						Math.random() * 100 - 50,
						Math.random() * 100 - 50,
						Math.random() * 100 - 50
					);
					v2.set(
						Math.random() * 100 - 50,
						Math.random() * 100 - 50,
						Math.random() * 100 - 50
					);

					// 将偏移向量加到基础位置上，得到三个顶点的实际位置
					v0.add(v);
					v1.add(v);
					v2.add(v);

					// 为这个三角形生成随机颜色
					color.setHex(Math.random() * 0xffffff);

					// 将第一个顶点的x,y,z坐标添加到顶点数组
					vertices.push(v0.x, v0.y, v0.z);
					vertices.push(v1.x, v1.y, v1.z);  // 第二个顶点
					vertices.push(v2.x, v2.y, v2.z);  // 第三个顶点

					// 将颜色值添加到颜色数组
					// 每个顶点需要三个颜色分量：红(r)、绿(g)、蓝(b)
					// 这里三个顶点使用相同的颜色
					colors.push(color.r, color.g, color.b);  // 第一个顶点的颜色
					colors.push(color.r, color.g, color.b);  // 第二个顶点的颜色
					colors.push(color.r, color.g, color.b);  // 第三个顶点的颜色
				}

				// 设置几何体的顶点位置属性
				// Float32BufferAttribute使用32位浮点数数组存储顶点数据
				// vertices - 顶点数据数组
				// 3 - 每个顶点由3个值组成（x, y, z）
				geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3));
				
				// 设置几何体的顶点颜色属性
				// colors - 颜色数据数组
				// 3 - 每个颜色由3个值组成（r, g, b）
				geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));

				// 使用创建的几何体和材质构建网格对象
				group = new THREE.Mesh(geometry, material);
				// 将整个三角形场放大2倍
				group.scale.set(2, 2, 2);
				// 添加到场景中
				scene.add(group);

				// =================== 创建精灵对象 ===================
				// 精灵(Sprite)是始终面向相机的2D图像
				// 常用于粒子效果、UI元素等
				for (let i = 0; i < 50; i++) {
					// 创建精灵材质，随机颜色
					const material = new THREE.SpriteMaterial({ color: Math.random() * 0xffffff });
					// 创建精灵对象
					const sprite = new THREE.Sprite(material);
					// 设置随机位置
					sprite.position.x = Math.random() * 1000 - 500;
					sprite.position.y = Math.random() * 1000 - 500;
					sprite.position.z = Math.random() * 1000 - 500;
					// 设置精灵尺寸：宽64、高64
					sprite.scale.set(64, 64, 1);
					// 添加到场景
					scene.add(sprite);
				}

				// =================== 创建自定义SVG对象 ===================
				// 创建SVG圆形元素
				// createElementNS：创建指定命名空间的元素
				// 'http://www.w3.org/2000/svg' - SVG命名空间
				const node = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
				// 设置SVG属性
				node.setAttribute('stroke', 'black');  // 边框颜色：黑色
				node.setAttribute('fill', 'red');      // 填充颜色：红色
				node.setAttribute('r', '40');          // 半径：40像素

				// 创建50个SVG对象并随机分布
				for (let i = 0; i < 50; i++) {
					// 创建SVGObject，克隆SVG节点
					// SVGObject允许将SVG元素作为3D对象放入Three.js场景
					const object = new SVGObject(node.cloneNode());
					// 设置随机位置
					object.position.x = Math.random() * 1000 - 500;
					object.position.y = Math.random() * 1000 - 500;
					object.position.z = Math.random() * 1000 - 500;
					// 添加到场景
					scene.add(object);
				}

				// =================== 从外部文件加载SVG ===================
				// 创建文件加载器
				const fileLoader = new THREE.FileLoader();
				// 异步加载SVG文件
				fileLoader.load('models/svg/hexagon.svg', function (svg) {
					// 创建SVG组(g)元素，用于包含加载的SVG内容
					const node = document.createElementNS('http://www.w3.org/2000/svg', 'g');
					
					// 创建DOM解析器，用于解析SVG字符串
					const parser = new DOMParser();
					// 将SVG字符串解析为XML文档
					const doc = parser.parseFromString(svg, 'image/svg+xml');
					
					// 将解析得到的SVG文档根元素添加到组中
					node.appendChild(doc.documentElement);

					// 创建SVGObject并添加到场景
					const object = new SVGObject(node);
					object.position.x = 500;  // 设置X轴位置
					scene.add(object);
				});

				// =================== 灯光设置 ===================
				// 创建环境光(AmbientLight)
				// 环境光均匀照射场景中的所有物体，没有方向性
				// 参数：光照颜色（十六进制）
				const ambient = new THREE.AmbientLight(0x80ffff);  // 浅青色
				scene.add(ambient);

				// 创建平行光(DirectionalLight)
				// 平行光从特定方向照射，产生明暗对比和阴影
				// 参数：光照颜色（十六进制）
				const directional = new THREE.DirectionalLight(0xffff00);  // 黄色
				// 设置光源方向向量
				// 向量(-1, 0.5, 0)表示光从右上方照射
				directional.position.set(-1, 0.5, 0);
				scene.add(directional);

				// =================== 渲染器设置 ===================
				// 创建SVG渲染器实例
				// SVGRenderer将3D场景渲染为SVG矢量图形
				// 优点：无限缩放不失真，适合打印和高分辨率显示
				// 缺点：性能较低，不适合复杂动态场景
				renderer = new SVGRenderer();
				
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置渲染质量
				// 'low'：较低质量，较高性能
				// 其他选项可能包括'medium'、'high'
				renderer.setQuality('low');
				
				// 将渲染器的DOM元素（SVG元素）添加到页面body中
				document.body.appendChild(renderer.domElement);

				// =================== 控制器设置 ===================
				// 创建轨道控制器
				// 参数1：要控制的相机
				// 参数2：事件监听的DOM元素
				controls = new OrbitControls(camera, renderer.domElement);
				// 启用阻尼效果
				// 阻尼使相机运动更加平滑，有惯性效果
				controls.enableDamping = true;

				// =================== 性能监视器设置 ===================
				// 创建性能监视器实例
				stats = new Stats();
				// 将性能监视器的DOM元素添加到页面
				// 默认显示帧率(FPS)
				document.body.appendChild(stats.dom);

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

			/**
			 * 窗口大小改变事件处理函数
			 * 当浏览器窗口大小改变时，确保3D场景正确适应新尺寸
			 */
			function onWindowResize() {
				// 更新相机纵横比
				// 纵横比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵
				// 当相机参数改变后，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();

				// 更新渲染器尺寸
				// 确保渲染器输出与窗口尺寸一致
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 这是游戏和动画应用的核心模式
			 * 使用requestAnimationFrame实现平滑动画
			 * 浏览器会在每次重绘前调用此函数
			 */
			function animate() {
				// 请求浏览器在下一帧重绘时调用animate函数
				// 这是实现动画的标准方法，比setInterval更高效
				requestAnimationFrame(animate);

				// 渲染当前帧
				render();
				
				// 更新性能监视器
				// 显示当前帧率等性能指标
				stats.update();
			}

			/**
			 * 渲染函数
			 * 负责更新场景状态并执行渲染
			 * 每一帧都会调用此函数
			 */
			function render() {
				// 更新三角形组的旋转
				// 每帧绕X轴旋转0.01弧度（约0.57度）
				// 这创建了持续旋转的动画效果
				group.rotation.x += 0.01;

				// 更新轨道控制器
				// 必须每帧调用，特别是启用了阻尼效果时
				controls.update();

				// 执行渲染
				// 将3D场景通过相机视角渲染到2D屏幕
				renderer.render(scene, camera);
			}

		</script>

	</body>
</html>