XinJiang/.agents/skills/coordinate-debug/SKILL.md

坐标系转换和3D模型调试技能

技能描述

此技能用于系统化处理 Three.js 项目中 3D 模型的坐标系转换和调试问题，特别适用于水利三维可视化场景。

适用场景

• 从不同 3D 软件（Blender、3ds Max、CAD）导出的模型坐标系不一致
• 模型出现倒置、朝向错误或位置偏移问题
• 需要调试 3D Tiles 渲染器和水面材质效果

工作流程

1. 问题识别阶段

目标: 确定模型来源和坐标系差异

步骤:

1. 识别模型来源软件：

   • Blender/3ds Max → Z-up 坐标系
   • Three.js → Y-up 坐标系
   • CAD 软件 → 可能使用 Z-up-forward-x

2. 检查模型问题：

   • 模型是否倒置（上下颠倒）
   • 朝向是否正确（前后左右）
   • 位置是否偏移

3. 收集调试信息：

   • 使用 coordinateDebug.ts 中的工具
   • 检查控制台输出的坐标信息
   • 记录模型的初始状态

2. 转换实施阶段

目标: 使用正确的参数进行坐标系转换

步骤:

1. 选择转换函数：

   import { convertCoordinateSystem } from '../utils/coordinateConverter'
   

2. 确定转换参数：

   • from: 源坐标系（'z-up', 'y-up', 'z-up-forward-x'）
   • to: 目标坐标系（默认 'y-up'）
   • rotationOption: 旋转选项
     • 'standard': 标准旋转
     • 'flipped': 翻转旋转（解决倒置问题）
     • '180': 180度旋转

3. 应用转换：

   const convertedModel = convertCoordinateSystem(
    model,
    'z-up',  // Blender 默认
    'y-up',  // Three.js 默认
    'flipped' // 如果模型倒置
   )
   

3. 调试验证阶段

目标: 验证转换效果和渲染质量

步骤:

1. 坐标调试：

   • 使用 showCoordinatePanel 查看拾取坐标
   • 检查 cameraInfo 验证相机位置
   • 使用 coordinateDebug.ts 工具验证转换

2. 渲染验证：

   • 检查水面材质是否正常显示
   • 验证 3D Tiles 渲染器加载状态
   • 测试相机控制和视角

3. 性能检查：

   • 监控渲染帧率
   • 检查内存使用情况
   • 验证 LOD（细节层次）效果

4. 常见问题处理

问题1: 模型倒置

症状: 模型上下颠倒 解决方案:

convertCoordinateSystem(model, 'z-up', 'y-up', 'flipped')

问题2: 朝向错误

症状: 模型前后左右方向错误 解决方案:

// 尝试不同的旋转选项
convertCoordinateSystem(model, 'z-up', 'y-up', 'standard')
convertCoordinateSystem(model, 'z-up', 'y-up', '180')

问题3: 材质显示异常

症状: 水面材质不显示或显示异常 解决方案:

1. 检查纹理坐标是否正确
2. 验证法线贴图是否加载
3. 调整材质参数（透明度、反射率等）

质量检查清单

转换前检查

• 确认模型来源软件
• 记录初始坐标系类型
• 备份原始模型文件

转换后验证

• 模型朝向正确（无倒置）
• 位置坐标符合预期
• 材质显示正常
• 相机控制响应正常

性能验证

• 渲染帧率稳定（>30fps）
• 内存使用合理
• LOD 切换正常

示例代码

基础坐标系转换

import * as THREE from 'three'
import { convertCoordinateSystem } from '../utils/coordinateConverter'

// 加载模型
const loader = new GLTFLoader()
loader.load('model.glb', (gltf) => {
  const model = gltf.scene
  
  // 转换坐标系（Blender → Three.js）
  const convertedModel = convertCoordinateSystem(
    model,
    'z-up',
    'y-up',
    'flipped'  // 如果模型倒置
  )
  
  // 添加到场景
  scene.add(convertedModel)
})

调试工具使用

import { showCoordinateInfo, showCameraInfo } from '../utils/coordinateDebug'

// 显示坐标信息
showCoordinateInfo(pickedPosition.value)

// 显示相机信息
showCameraInfo(cameraInfo.value)

相关工具和函数

主要工具

• convertCoordinateSystem: 坐标系转换核心函数
• coordinateDebug.ts: 调试工具集合
• Scene3D.vue: 3D 场景组件（包含调试面板）

配置文件

• sceneConfig.ts: 场景配置和材质参数
• coordinateConverter.ts: 坐标系转换矩阵定义

最佳实践

1. 备份优先: 转换前备份原始模型
2. 逐步验证: 每次只改变一个参数
3. 记录日志: 记录转换参数和结果
4. 团队协作: 与 3D 艺术家沟通坐标系要求

技能输出

此技能将帮助用户：

1. 系统化识别和解决坐标系问题
2. 正确使用转换工具和参数
3. 有效调试 3D 模型和渲染效果
4. 建立标准化的坐标系处理流程

示例提示语

• "我的 Blender 模型导入 Three.js 后倒置了，如何解决？"
• "如何调试 3D Tiles 渲染器的坐标系问题？"
• "水面材质显示异常，可能是坐标系问题吗？"
• "如何批量转换多个模型的坐标系？"