前端交互式 3D 人体肌肉解剖图：Three.js + React Three Fiber 实战

前端实现交互式 3D 人体肌肉解剖展示

在前端构建一个交互式的 3D 人体肌肉解剖工具，核心目标是让用户能在浏览器中旋转、缩放模型，并点击任意肌肉查看对应的中英文名称。这比依赖静态图片或昂贵软件的学习方式要直观得多。

技术架构概览

整个方案运行在浏览器端，无需后端服务介入。数据流大致如下：

1. 资源层：使用 Draco 压缩的 GLB 模型作为基础资产。
2. 渲染层：通过 React Three Fiber (R3F) 管理 Three.js 场景与生命周期。
3. 交互层：利用 Raycaster 进行射线检测，配合材质属性变化实现高亮反馈。
4. 数据层：维护肌肉 ID 映射表及多语言翻译文件。

模型来源与处理

开源模型准备

我们基于 Z-Anatomy 项目获取原始解剖数据。该 Blender 项目包含完整的人体结构，原始文件较大（约 300MB），包含上千个独立网格对象。为了适应 Web 环境，必须进行导出和压缩。

导出与压缩流程

将 Blender 文件导出为 GLB 格式是关键一步。我们需要编写脚本筛选出肌肉相关的对象，并启用 Draco 压缩算法。

# export_cli.py - Blender 命令行导出脚本
import bpy

# 定义肌肉关键词
muscle_keywords = [
    'muscle', 'deltoid', 'bicep', 'tricep', 
    'pectoralis', 'latissimus', 'trapezius'
]

for obj in bpy.data.objects:
    if obj.type == 'MESH':
        name_lower = obj.name.lower()
        # 仅选中包含关键词的对象
        if any(keyword in name_lower for keyword in muscle_keywords):
            obj.select_set(True)

# 导出为 GLB，开启 Draco 压缩
bpy.ops.export_scene.gltf(
    filepath='muscle-anatomy.glb',
    export_format='GLB',
    use_selection=True,
    export_draco_mesh_compression_enable=True,
    export_draco_mesh_compression_level=6,
)

经过处理，模型体积从 300MB 降至 6.8MB 左右，非常适合 Web 加载。

核心实现细节

1. 搭建 3D 场景

使用 R3F 的 Canvas 组件包裹整个场景。这里需要配置相机位置、光照以及轨道控制器，方便用户自由观察。

// muscle-scene.tsx
import { Canvas } from '@react-three/fiber';
import { OrbitControls, Environment } from '@react-three/drei';

export function MuscleScene({ onMuscleClick, hoveredMuscle, selectedMuscle }) {
  return (
    <Canvas camera={{ position: [1.5, 0.3, 2], fov: 50 }}>
      {/* 环境光照 */}
      <ambientLight intensity={0.6} />
      <directionalLight position={[5, 5, 5]} intensity={0.8} />
      
      {/* 3D 模型 */}
      <Suspense fallback={null}>
        <MuscleModel 
          onMuscleClick={onMuscleClick} 
          hoveredMuscle={hoveredMuscle} 
          selectedMuscle={selectedMuscle} 
        />
      </Suspense>
      
      {/* 轨道控制器 */}
      <OrbitControls 
        enablePan={false} 
        minDistance={1} 
        maxDistance={5} 
        target={[0, 0.5, 0]} 
      />
      
      {/* 环境贴图 */}
      <Environment preset="studio" />
    </Canvas>
  );
}

2. 模型加载与过滤

加载 GLB 后，我们需要遍历场景树，剔除骨骼、筋膜等非肌肉对象，并为肌肉部分应用统一的初始材质。

// muscle-model.tsx
import { useGLTF } from '@react-three/drei';
import * as THREE from 'three';
import { useMemo } from 'react';

const muscleKeywords = [
  'muscle', 'deltoid', 'bicep', 'pectoralis', 
  'rectus', 'gluteus', 'quadricep', 'gastrocnemius'
];

const HIDDEN_KEYWORDS = [
  'region', 'fascia', 'bursa', 'ligament', '.j', '.t'
];

function isMuscle(name: string): boolean {
  const lowerName = name.toLowerCase();
  return muscleKeywords.some(k => lowerName.includes(k)) && 
         !HIDDEN_KEYWORDS.some(k => lowerName.includes(k));
}

export function MuscleModel({ onMuscleClick, hoveredMuscle, selectedMuscle }) {
  const { scene } = useGLTF('/models/muscle-anatomy.glb');

  // 克隆场景并处理材质，避免影响全局
  const clonedScene = useMemo(() => {
    const clone = scene.clone(true);
    clone.traverse((child) => {
      if (child instanceof THREE.Mesh) {
        if (!isMuscle(child.name)) {
          child.parent?.remove(child);
          return;
        }
        // 设置默认红色系材质
        child.material = child.material.clone();
        child.material.color = new THREE.Color(0xc44d4d);
        child.material.roughness = 0.7;
        child.material.metalness = 0.1;
      }
    });
    return clone;
  }, [scene]);

  return (
    <primitive 
      object={clonedScene} 
      position={[0, -0.84, 0]}
      onClick={onMuscleClick}
    />
  );
}

3. 交互高亮效果

为了让用户感知到当前选中的肌肉，我们利用材质的 emissive 属性。悬停时显示薄荷绿，选中时显示深绿色。

// 高亮颜色配置
const HIGHLIGHT_COLOR = new THREE.Color(0x5ac57a); // 悬停
const SELECTED_COLOR = new THREE.Color(0x4caf50);  // 选中

useEffect(() => {
  clonedScene.traverse((child) => {
    if (child instanceof THREE.Mesh && isMuscle(child.name)) {
      const material = child.material as THREE.MeshStandardMaterial;
      const muscleId = getMuscleIdFromModelName(child.name);
      const isHovered = muscleId === hoveredMuscle;
      const isSelected = muscleId === selectedMuscle;

      if (isSelected) {
        material.emissive = SELECTED_COLOR;
        material.emissiveIntensity = 0.5;
      } else if (isHovered) {
        material.emissive = HIGHLIGHT_COLOR;
        material.emissiveIntensity = 0.3;
      } else {
        material.emissive = new THREE.Color(0x000000);
        material.emissiveIntensity = 0;
      }
    }
  });
}, [hoveredMuscle, selectedMuscle, clonedScene]);

4. 名称映射与多语言支持

Z-Anatomy 的命名包含左右侧后缀（如 .l, .r），我们需要清洗这些后缀并映射到标准肌肉 ID。同时维护一份中英文对照表。

// muscles.ts
const muscleAliases: Record<string, string[]> = {
  'pectoralis_major': [
    'pectoralis major', 
    'sternocostal head of pectoralis major'
  ],
  'biceps_brachii': ['biceps brachii', 'long head of biceps brachii'],
};

export function getMuscleIdFromModelName(modelName: string): string | undefined {
  const cleanName = modelName
    .replace(/\.(l|r|el|er)$/i, '')
    .toLowerCase()
    .trim();

  for (const [muscleId, aliases] of Object.entries(muscleAliases)) {
    if (aliases.some(alias => cleanName.includes(alias))) {
      return muscleId;
    }
  }
  return undefined;
}

性能优化建议

1. 模型压缩：Draco 是必须的，能显著减少网络传输时间。
2. 动态加载：对于 Next.js 项目，建议使用 dynamic 导入禁用 SSR，因为 3D 场景无法在服务端正确渲染。
3. 材质复用：不要频繁创建新材质实例，修改现有材质的 emissive 属性即可。

总结

这套方案完全在浏览器端运行，核心技术点在于模型预处理、React Three Fiber 的场景管理以及射线检测交互逻辑。通过 Draco 压缩和多语言映射，实现了轻量级的 3D 可视化教学工具。