《LearningCell》代码析微

项目缘起

近岁，GitHub上有一项目，乃基于三维之模型，为细胞之学究平台。此平台之旨，在助人通过三维模型，习细胞之根本概念与功用。

其代码所依之址为：《LearningCell》

此项目之代码简短，甚为易解，随三维高斯泼溅之术日臻完善，三维网络之道亦将迎新用与新突破。

其技术之骨如下：

• 前端：React合TypeScript，以Vite为器
• 三维模型：GLTF之式
• 三维模型之载：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中，吾定装载模型之函数，以载三维之模。
首者，自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之钩，以候模型之载。及模型载毕，乃将其入于场景之中。

/**
 * 将 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>
  );
}