React + Three-Fiber 中InstancedMesh实例无法正常显示

问题现象 #

• 开发3D分子可视化功能时，需要在分子周围渲染大量小球体粒子
• 基于React Three Fiber的instancedMesh实例化渲染特性实现时，无任何粒子实例被渲染
• 预期效果参考ElectronVisualized项目，示例效果如下：
  

原问题代码 #

import * as THREE from "three";

import { useEffect, useState, useMemo, useRef } from "react";

import { useSelector } from "react-redux";

import { getMoleculeColour, getMoleculeOpacity } from "./Globals";

export function Particles({ particleRadius }) {
  const tempObject = useMemo(() => new THREE.Object3D(), []);
  const tempColor = useMemo(() => new THREE.Color(), []);

  const [counter, setCounter] = useState(0);

  const meshRef = useRef();
  const colorRef = useRef();

  const globalAtomInfo = useSelector((state) => state.atomInfo.globalAtomInfo);

  const globalSelectedElement = useSelector(
    (state) => state.selectedElement.globalSelectedElement
  );

  useEffect(() => {
    if (meshRef === null) return;
    if (meshRef.current === null) return;

    const mesh = meshRef.current;

    for (const [key, value] of Object.entries(globalAtomInfo["density_data"])) {
      const coords = key.split(", ");
      const volume = value;

      //position
      tempObject.position.set(
        coords[0] / 5 - 10.7,
        coords[1] / 5 - 10.7,
        coords[2] / 5 - 10.7
      );

      tempObject.updateMatrix();
      mesh.setMatrixAt(counter, tempObject.matrix);

      // color
      mesh.setColorAt(
        counter,
        tempColor.setRGB(
          ...getMoleculeColour(globalSelectedElement["element"], volume)
        )
      );

      setCounter(counter + 1);
      
      console.log(meshRef.current)
    }
  });

  return (
    // Generate particles...
    <instancedMesh
      ref={meshRef}
      args={[null, null, globalAtomInfo["density_data"].length]}
    >
      <sphereBufferGeometry args={[particleRadius, 30, 30]} attach="geometry" />

      <meshBasicMaterial
        transparent={true}
        opacity={1.0}
        //   opacity={getMoleculeOpacity(
        //     globalSelectedElement["element"],
        //     volume
        //   )}
        attach="material"
      />
    </instancedMesh>
  );
}

核心错误点 #

1. useEffect配置错误：未传入依赖数组，每次组件重渲染都会重复执行逻辑；循环内调用setCounter会触发无限重渲染，导致实例数据反复被覆盖。
2. 实例索引逻辑错误：循环内使用state变量counter作为实例索引，state更新是异步的，整个循环过程中counter始终为初始值0，所有实例的矩阵、颜色数据都会被写到第0个实例位置，其余实例为空。
3. 缺少GPU同步标记：调用setMatrixAt、setColorAt修改实例数据后，未将对应缓冲区的needsUpdate属性设为true，Three.js不会将修改后的数据同步到GPU，渲染时使用的始终是初始空数据。
4. 坐标类型隐式转换风险：从key中拆分出的坐标值为字符串类型，直接传入位置计算可能出现坐标异常，导致粒子生成在视锥体范围外。
5. 冗余空值判断：useRef返回的ref对象本身永远不会为null，仅需判断meshRef.current即可。

修复后完整代码 #

import * as THREE from "three";
import { useEffect, useMemo, useRef } from "react";
import { useSelector } from "react-redux";
import { getMoleculeColour } from "./Globals";

export function Particles({ particleRadius }) {
  const tempObject = useMemo(() => new THREE.Object3D(), []);
  const tempColor = useMemo(() => new THREE.Color(), []);
  const meshRef = useRef();

  const globalAtomInfo = useSelector((state) => state.atomInfo.globalAtomInfo);
  const globalSelectedElement = useSelector(
    (state) => state.selectedElement.globalSelectedElement
  );

  const densityData = globalAtomInfo["density_data"];
  const particleCount = Object.keys(densityData).length;

  useEffect(() => {
    if (!meshRef.current) return;
    const mesh = meshRef.current;
    let index = 0;

    for (const [key, volume] of Object.entries(densityData)) {
      const [x, y, z] = key.split(", ");
      // 显式转换为数值类型，避免隐式转换异常
      const posX = Number(x) / 5 - 10.7;
      const posY = Number(y) / 5 - 10.7;
      const posZ = Number(z) / 5 - 10.7;

      // 设置当前实例变换矩阵
      tempObject.position.set(posX, posY, posZ);
      tempObject.updateMatrix();
      mesh.setMatrixAt(index, tempObject.matrix);

      // 设置当前实例颜色
      const [r, g, b] = getMoleculeColour(globalSelectedElement.element, volume);
      tempColor.setRGB(r, g, b);
      mesh.setColorAt(index, tempColor);

      index++;
    }

    // 强制同步实例数据到GPU
    mesh.instanceMatrix.needsUpdate = true;
    if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
  // 仅在依赖数据变化时重新计算实例
  }, [densityData, globalSelectedElement, particleRadius, tempObject, tempColor]);

  return (
    <instancedMesh ref={meshRef} args={[null, null, particleCount]}>
      <sphereBufferGeometry args={[particleRadius, 30, 30]} attach="geometry" />
      <meshBasicMaterial transparent opacity={1.0} attach="material" />
    </instancedMesh>
  );
}

后续优化提示 #

• 若需要实现逐实例透明度变化，默认instancedMesh不支持直接设置逐实例透明度，可开启材质的vertexColors属性，将透明度打包到颜色Alpha通道，或使用自定义着色器实现。
• 粒子总量超过10万时，建议降低球体分段数，或使用Points配合圆点纹理替代实体球体，大幅提升渲染性能。
• 若修复后仍看不到粒子，可打印粒子坐标范围，确认相机视锥体覆盖了粒子所在区域，避免粒子生成在可视范围外。

内容的提问来源于stack exchange，提问作者John Seong