LearningCell代码解读
项目介绍
最近，GitHub上有一个很火的项目，一个基于 3D 模型的细胞学习平台。该平台的目标是帮助用户通过 3D 模型学习细胞的基本概念和功能。
代码地址为：LearningCell
项目代码很短很少，非常简单，随着3d高斯泼溅效果的不断完善，3D-WEB也快迎来了新的应用和突破。
项目的技术栈如下：
- 前端：React + TypeScript + Vite
- 3D 模型：GLTF 格式
- 3D 模型加载：Draco 压缩
目录结构
.
├── .github/workflows/deploy.yml # GitHub Pages 自动部署
├── README.md
├── app/ # Vite 前端工程
│ ├── public/
│ │ ├── draco/ # 自带的 Draco 解码器
│ │ ├── images/ # 细胞缩略图（已压缩）
│ │ └── models/ # 5 个 .glb 模型
│ ├── src/
│ │ ├── components/ # UI 组件（侧栏、3D 查看器、信息面板等）
│ │ ├── data/models.ts # 5 个生物概念的数据
│ │ ├── hooks/useModel.ts # 加载状态订阅 hook
│ │ ├── lib/modelLoader.ts # 流式下载 + Draco 解析 + 缓存
│ │ ├── App.tsx
│ │ └── ...
│ └── package.json
└── （根目录其它是源文件备份，例如未压缩的 PNG 与 .draco.glb 原始资源）
代码解析
1，入口代码
在App.tsx中，我们使用useEffect来加载默认模型和预加载其它模型。
useEffect(() => {let cancelled = false;const firstEntry = loadModel(activeModel.modelUrl, {fileSize: activeModel.fileSize,});let started = false;const queueOthers = () => {if (cancelled || started) return;started = true;const queue = MODELS.filter((m) => m.id !== activeModel.id);let i = 0;const next = () => {if (cancelled || i >= queue.length) return;const m = queue[i++];preloadModel(m.modelUrl, { fileSize: m.fileSize });const entry = getLoadEntry(m.modelUrl);entry?.promise.finally(() => {if (cancelled) return;setTimeout(next, 120);});};next();};}
2，模型加载代码
在modelLoader.ts中，我们定义了loadModel函数，用于加载3D模型。
首先是从URL中获取模型的文件大小，然后使用fetchWithProgress函数来流式下载模型。但是在本项目中是不需要用到下载，而是直接加载模型；
加载器直接基于three.js的GLTFLoader和DRACOLoader来加载模型。
import { GLTFLoader, type GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
详细的实现函数如下
export function loadModel(url: string, options: LoadOptions): LoadEntry {const existing = cache.get(url);if (existing) return existing;const entry: LoadEntry = {status: 'downloading',progress: 0,listeners: new Set(),promise: Promise.resolve() as unknown as Promise<GLTF>,};cache.set(url, entry);notifyCache();entry.promise = (async () => {try {const buffer = await fetchWithProgress(url, options.fileSize, (loaded, total) => {entry.status = 'downloading';entry.progress = Math.min(0.95, (loaded / Math.max(1, total)) * 0.95);notifyEntry(entry);});entry.buffer = buffer;entry.status = 'parsing';entry.progress = 0.97;notifyEntry(entry);const gltf = await parseGLTF(buffer, '');entry.gltf = gltf;entry.status = 'done';entry.progress = 1;notifyEntry(entry);return gltf;} catch (error) {entry.status = 'error';entry.error = error;notifyEntry(entry);throw error;}})();return entry;
}3，模型渲染代码
具体的实现是在ModelScene.tsx中，我们使用useModel hook来订阅模型加载状态，当模型加载完成后，我们将模型添加到场景中。
/*** 将 GLTF.scene 居中、缩放到合适大小后渲染。* 通过 useFrame 实现可控的自动旋转。*/
export function ModelScene({gltf,autoRotate,initialRotationY = 0,displayScale = 1,
}: Props) {const groupRef = useRef<THREE.Group>(null);const { centeredScene, scale } = useMemo(() => {const cloned = cloneScene(gltf); // 调用工具函数克隆场景，确保每个组件实例拥有独立的模型副本const box = new THREE.Box3().setFromObject(cloned); // 计算模型的包围盒，获取模型的空间范围const size = new THREE.Vector3();box.getSize(size);const center = new THREE.Vector3();box.getCenter(center); // 通过将模型位置减去包围盒中心点坐标，实现几何中心对齐原点 cloned.position.x -= center.x;cloned.position.y -= center.y;cloned.position.z -= center.z;const maxDim = Math.max(size.x, size.y, size.z) || 1;const targetSize = 2.0;return {centeredScene: cloned,scale: (targetSize / maxDim) * displayScale,};}, [gltf, displayScale]);// 切换模型时重置旋转到默认角度 (当切换模型或修改初始旋转角度时，重置模型到指定的初始姿态。)useEffect(() => {if (groupRef.current) {groupRef.current.rotation.set(0, initialRotationY, 0);}}, [initialRotationY, gltf]);useFrame((_, delta) => { // 每一帧更新模型的旋转角度，实现自动旋转效果。if (autoRotate && groupRef.current) {groupRef.current.rotation.y += delta * 0.25; // 每一帧增加0.25弧度的旋转角度，实现自动旋转效果。}});return (<group ref={groupRef} scale={scale} rotation={[0, initialRotationY, 0]}><primitive object={centeredScene} /></group>);
}