vue-model-review/ANNOTATION_GUIDE.md

# 模型标注配置指南

## 概述

本指南说明如何将3D模型的部件与检查项目（annotations）精确匹配，实现准确的标注定位。

## 方法一：使用调试组件查看模型结构

### 1. 启用调试模式

在 `ModelDetail.vue` 中使用 `ThreeViewerDebug` 组件并启用调试模式：

```vue
<template>
  <div class="model-detail">
    <three-viewer-debug
      :model-path="modelPath"
      :annotations="modelData.componentCheck"
      :debug-mode="true"
      @annotation-click="handleAnnotationClick"
      @model-loaded="handleModelLoaded"
    />
  </div>
</template>

<script>
import ThreeViewerDebug from '../components/ThreeViewerDebug.vue'

export default {
  components: {
    ThreeViewerDebug
  }
}
</script>
```

### 2. 查看模型部件列表

启用调试模式后，右侧会显示调试面板，包含：
- 模型中所有mesh的名称列表
- 点击模型部件可查看其名称和坐标

### 3. 记录部件信息

1. 打开浏览器控制台（F12）
2. 查看控制台输出的"模型部件列表"和"部件映射表"
3. 点击模型上的部件，查看其名称和坐标
4. 点击"复制坐标"按钮，将坐标复制到剪贴板

## 方法二：通过命名匹配（推荐）

### 自动匹配规则

组件会自动尝试匹配 `componentCheck` 中的 `name` 与模型mesh的名称：

1. **精确匹配**：mesh名称完全等于annotation名称
2. **包含匹配**：mesh名称包含annotation名称，或反之
3. **关键词匹配**：拆分annotation名称，匹配关键词

### 示例

如果模型中有以下mesh名称：
```
- 引线_001
- 避雷器本体
- 铭牌标识
- 螺栓组件
- 线夹装置
- 绝缘罩_上
- 绝缘罩_下
```

data.json中的配置：
```json
{
  "componentCheck": [
    { "name": "引线", "content": [...] },           // 匹配 "引线_001"
    { "name": "避雷器与支撑件结构", "content": [...] }, // 匹配 "避雷器本体"
    { "name": "铭牌", "content": [...] },           // 匹配 "铭牌标识"
    { "name": "螺栓螺母", "content": [...] },       // 匹配 "螺栓组件"
    { "name": "线夹", "content": [...] },           // 匹配 "线夹装置"
    { "name": "绝缘罩", "content": [...] }          // 匹配 "绝缘罩_上" 或 "绝缘罩_下"
  ]
}
```

## 方法三：手动配置坐标

如果模型没有命名或命名不规范，可以手动配置坐标。

### 1. 在data.json中添加position字段

```json
{
  "componentCheck": [
    {
      "name": "避雷器与支撑件结构",
      "position": { "x": 0, "y": 1.5, "z": 0 },
      "content": [...]
    },
    {
      "name": "引线",
      "position": { "x": 0.5, "y": 2.0, "z": 0.3 },
      "content": [...]
    },
    {
      "name": "铭牌",
      "position": { "x": -0.3, "y": 0.5, "z": 0.2 },
      "content": [...]
    }
  ]
}
```

### 2. 修改组件以支持position配置

在 `createAnnotations()` 方法中添加：

```javascript
createAnnotations() {
  this.annotations.forEach((annotation, index) => {
    let position = new THREE.Vector3();
    
    // 优先使用配置的坐标
    if (annotation.position) {
      position.set(
        annotation.position.x,
        annotation.position.y,
        annotation.position.z
      );
    } else {
      // 否则尝试匹配mesh
      const mesh = this.findMeshByName(annotation.name);
      if (mesh) {
        mesh.getWorldPosition(position);
        // ...
      }
    }
    // ...
  });
}
```

## 获取坐标的步骤

### 使用调试模式

1. 启用 `debugMode="true"`
2. 运行项目，打开模型详情页
3. 点击模型上的部件
4. 查看右侧调试面板显示的坐标
5. 点击"复制坐标"按钮
6. 将坐标粘贴到data.json的对应位置

### 使用控制台

1. 打开浏览器控制台（F12）
2. 点击模型部件
3. 查看控制台输出：
   ```
   点击的部件: {
     name: "引线_001",
     position: { x: 0.523, y: 2.145, z: 0.312 }
   }
   ```
4. 复制坐标到data.json

## 完整示例

### data.json配置

```json
{
  "modelName": "交流避雷器",
  "modelPath": "1",
  "componentCheck": [
    {
      "name": "避雷器与支撑件结构",
      "meshName": "避雷器本体",
      "position": { "x": 0, "y": 1.5, "z": 0 },
      "content": [
        "避雷器与支撑件并列结构...",
        "避雷器在本体失效或损坏后..."
      ]
    },
    {
      "name": "引线",
      "meshName": "引线_001",
      "position": { "x": 0.5, "y": 2.0, "z": 0.3 },
      "content": [
        "不低于 80cm，直径不低于 16mm 的软铜线"
      ]
    }
  ]
}
```

### ModelDetail.vue使用

```vue
<template>
  <div class="model-detail">
    <!-- 开发阶段使用调试版本 -->
    <three-viewer-debug
      v-if="isDevelopment"
      :model-path="modelPath"
      :annotations="modelData.componentCheck"
      :debug-mode="true"
      @annotation-click="handleAnnotationClick"
    />
    
    <!-- 生产环境使用正式版本 -->
    <three-viewer
      v-else
      :model-path="modelPath"
      :annotations="modelData.componentCheck"
      @annotation-click="handleAnnotationClick"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      isDevelopment: process.env.NODE_ENV === 'development'
    }
  }
}
</script>
```

## 注意事项

1. **坐标系统**：Three.js使用右手坐标系，Y轴向上
2. **模型居中**：组件会自动将模型居中，坐标相对于模型中心
3. **标注高度**：标注会自动放置在部件上方约0.3单位处
4. **命名规范**：建议在建模时为重要部件命名，便于自动匹配
5. **性能考虑**：过多的标注可能影响性能，建议控制在10个以内

## 故障排查

### 标注不显示
- 检查 `labelRenderer.render()` 是否在动画循环中调用
- 检查标注位置是否在相机视野内
- 检查CSS样式是否正确

### 无法匹配部件
- 使用调试模式查看模型部件列表
- 检查mesh是否有命名
- 考虑使用手动配置坐标

### 高亮不生效
- 检查是否正确传递mesh对象
- 确认OutlinePass已正确初始化
- 查看控制台是否有错误信息

## 相关文件

- `src/components/ThreeViewerDebug.vue` - 调试版本组件
- `src/components/ThreeViewer.vue` - 生产版本组件
- `src/data/data.json` - 模型数据配置
- `src/views/ModelDetail.vue` - 详情页面