MetaFusion/README.md

Always respond in 中文，

先阅读知识库，并按照 Readme.md 来查看文件路径以及参考品文档和参考代码来协助用户完成项目

# MetaFusion 开发文档

## 一 本地知识库导航

### 1 文档

- [Metahuman解析](./docs/Metahuman解析.md)
- [SuperRigging解析](./Reference/docs/SuperRigging解析.pdf)
- [DNA_Calibration 文档](./Reference/docs/DNA_Calibration.pdf)
- [DNA_Calibration在线文档](https://epicgames.github.io/MetaHuman-DNA-Calibration/)
- [Metahuman解析](./Reference/docs/Metahuman解析.pdf)
- [SuperRiggingEditor使用文档](./Reference/docs/SuperRiggingEditor使用文档.pdf)


### 2 代码参考

- [Metahuman](./Reference/Metahuman)
- [SuperRigging](./Reference/SuperRigging)
- [MSLiveLink](./Reference/MSLiveLink)
- [DNA_Calibration](./Reference/DNA_Calibration)
- [功能实现参考](./Reference/Utils)

### 3 UI参考

- [UI参考图片](./Reference/UI)

## 二 项目描述

### 1 目标

  做一个Maya的Metahuman自定义的插件，语言:基于Python，Maya版本:2022, 2023, 2024, 2025

### 项目描述

- 本项目是一个Maya插件，主要功能是提供与MetaHuman相同拓扑的模型或者自定义的3d模型以来完成自定义绑定，编辑DNA，校准骨骼位置，保存DNA，载入DNA，导出fbx，保存DNA文件, 编辑BlendShape,等功能。

### 2 主要功能

- 提供与MetaHuman相同拓扑的模型或者自定义的3d模型以来完成自定义绑定，编辑DNA，校准骨骼位置，保存DNA，载入DNA，导出fbx，保存DNA文件, 编辑BlendShape,等功能。

### 3 注意Reference路径不参与参见功能实现，只作为参考。Reference只作为参考，可以从中拷贝必要的文件到当前项目中

### 4 代码规范

- 所有代码必须使用UTF-8编码
- 所有模块开头必须添加 ：

```.
#!/usr/bin/env python
# -*- coding: utf-8 -*-
```

- 代码必须考虑兼容 Maya2022, Maya2023, Maya2024, Maya2025
- 代码必须考虑兼容 Python3.10, Python3.11, Python3.12
- 所有模型引用关系自动更新修正
- UI样式必须统一的一个样式文件来实现
- 所有UI必须使用Qt来实现
- 所有Pyside代码必须使用 widget, layout, connection 的结构来实现
- 文件夹结构尽量以目前的代码结构来触发实现，各个模块各功能给要条理清晰
- 使用config.py文件来统一实现配置文件
- 使用style.qss文件来实现UI样式
- 功能函数放在utils文件夹中

### 5 文件基本结构 （参考）, 以"\"结尾的行为文件夹

- 参考[MetaFusion 文件基本结构](#metafusion-文件基本结构)

#### MetaFusion 文件基本结构

```.
├── assets\
│   ├── dna\                          DNA文件路径
│   ├── img\                          DNA图标路径
│   ├── maya\                         Maya资源文件路径
│   ├── MH.2\                         MetaHuman 2.0文件路径
│   ├── MH.4\                         MetaHuman 4.0文件路径
├── icons\                            插件图标路径
├── plugins\
│   └── Linux\
│   │   ├── 2022\
│   │   ├── 2023\
│   │   ├── 2024\
│   │   ├── 2025\
│   │   ├── pydna\
│   │   │   ├── python3\
│   │   │   ├── python311\
│   │   │   ├── python397\
│   │   │   ├── python3108\
│   └── Windows\
│   │   ├── 2022\
│   │   ├── 2023\
│   │   ├── 2024\
│   │   ├── 2025\
│   │   ├── pydna\
│   │   │   ├── python3\
│   │   │   ├── python311\
│   │   │   ├── python397\
│   │   │   ├── python3108\
├── Reference\                       参考模块（不引用，仅供参考）
│   ├── DNA_Calibration              参考模块：DNA_Calibration
│   ├── MSLiveLink                   参考模块：MSLiveLink
│   ├── SuperRiggingEditor           参考模块：SuperRiggingEditor
├── scripts\
│   ├── builder\
│   │   ├── maya\
│   │   │   ├── __init__.py
│   │   │   ├── mesh.py
│   │   │   ├── skin_weights.py
│   │   │   ├── util.py
│   │   ├── __init__.py
│   │   ├── builder.py
│   │   ├── config.py
│   │   ├── joint.py
│   │   ├── mesh.py
│   │   ├── rig_builder.py
│   ├── dnacalib\
│   │   ├── CMakeModulesExtra\
│   │   ├── DNACalib\
│   │   ├── PyDNA\
│   │   ├── PyDNACalib\
│   │   ├── SPyUS\
│   │   ├── CMakeLists.txt
│   ├── dnalib\
│   │   ├── __init__.py
│   │   ├── behavior.py
│   │   ├── definition.py
│   │   ├── descriptor.py
│   │   ├── dnalib.py
│   │   ├── geometry.py
│   │   ├── layer.py
│   ├── ui\
│   │   ├── __init__.py
│   │   ├── style.qss                   UI样式文件
│   │   ├── main.ui                     UI主界面UI文件
│   ├── utils\                          功能模块路径
│   │   ├── __init__.py
│   │   ├── ...                         
│   ├── MetaFusion.py                   插件主文件
│   ├── config.py                       配置文件                   
├── Install.mel                         拖入maya安装文件
├── Install.py                          安装执行文件
├── CleanPycache.bat                    清除pycache文件（不修改）
├── README.md                           开发文档
```

### 6 UI界面风格

- 扁平化设计风格，
- 要有高级感和科幻未来感
- 圆角设计
- 中文要清晰大气
- 英文要简洁明了
- 颜色要统一
- 字体要统一
- 字体大小要统一
- 按钮要统一
- 输入框要统一
- 标签要统一

### 7 UI界面

- 参考[MetaFusion UI 结构](#metafusion-ui-结构)

#### MetaFusion UI 结构

##### 一、菜单栏

###### 1. 文件菜单 (File)

- 打开 DNA | icons\open.png
- 保存 DNA | icons\save.png
- 加载当前项目 DNA | icons\open.png
- 修改混合目标名称 | icons\rename.png
- 重置混合目标名称 | icons\resetname.png
- 导出 FBX | icons\export.png
- 退出 | icons\exit.png

###### 2. 编辑菜单 (Edit)

- 创建 RL4 节点 | icons\connect.png
- 删除 RL4 节点 | icons\disconnect.png
- 镜像左至右 | icons\mirrorL.png
- 镜像右至左 | icons\mirrorR.png
- 姿势由 A 型转 T 型 | icons\pose_A_To_T.png
- 姿势由 T 型转 A 型 | icons\pose_T_To_A.png
- 传输 LOD 贴图 | icons\locator.png
- 设置关节颜色 | icons\color.png
- 取消全部标记 | icons\unmark_all.png
- 重建所有目标 | icons\rebuildTargets.png
- 为所有表情设置关键帧 | icons\bakeAnimation.png
- 烘焙所有表情的关键帧 | icons\centerCurrentTime.png

###### 3. 工具菜单 (Tools)

- 导出蒙皮 | icons\export_skin.png
- 导入蒙皮 | icons\import_skin.png
- 拷贝装皮 | icons\copy_skin.png
- RBF变形器 | icons\blendShape.png
- 快速绑定服装 | icons\clothing_weight.png
- 克隆混合变形 | icons\blendShape.png
- UV传递点序 | icons\repair_vertex_order.png
- 面部生成控制器 | icons\controller.png
- 提取52BS | icons\ARKit52.png
- 关节轴向修复 | icons\joint.png
- 生成身体控制器 | icons\create_body_ctrl.png
- 导入面部动画 | icons\import_face_anim.png
- 导入身体动画 | icons\import_body_anim.png

###### 4. 语言菜单 (Language)

- 中文 | icons\chinese.png
- English | icons\english.png

###### 5. 帮助菜单 (Help)

- 检查更新 | icons\update.png
- 帮助文档 | icons\help.png
- 关于 | icons\about.png

##### 二、工具架 横向排列

- 保存 DNA | icons\save.png
- 加载当前项目 DNA | icons\open.png
- 分隔符 separator
- 创建RL4节点 | icons\connect.png
- 删除RL4节点 | icons\disconnect.png
- 分隔符 separator
- 导出 蒙皮 | icons\export_skin.png
- 导入 蒙皮 | icons\import_skin.png
- 复制 蒙皮 | icons\copy_skin.png
- 分隔符 separator
- 帮助文档 | icons\help.png
- 关于 | icons\about.png

##### 三、主界面功能区

###### 1. 模型视图 (Meshes)

####### LOD选项卡 (LOD0-LOD7)

每个LOD包含以下模型项：

- LOD0: ["*头部", "*牙齿", "*牙龈", "*左眼", "*右眼", "*虹膜", "*睫毛", "*眼睑", "*软骨", "*身体"]
- LOD1: ["头部", "牙齿", "牙龈", "左眼", "右眼", "虹膜", "睫毛", "眼睑", "软骨", "身体"]
- LOD2: ["头部", "牙齿", "牙龈", "左眼", "右眼", "虹膜", "睫毛", "眼睑", "身体"]
- LOD3: ["头部", "牙齿", "左眼", "右眼", "虹膜", "睫毛", "眼睑", "身体"]
- LOD4: ["头部", "牙齿", "左眼", "右眼", "虹膜"]
- LOD5: ["头部", "牙齿", "左眼", "右眼"]
- LOD6: ["头部", "牙齿", "左眼", "右眼"]
- LOD7: ["头部", "牙齿", "左眼", "右眼"]

####### 功能按钮

1. 自动选择模型
- 功能：根据当前LOD级别自动选择对应的模型组件
- 使用场景：快速选择特定LOD级别下的所有相关模型

2. 标准化命名
- 功能：将选中模型重命名为标准命名格式
- 使用场景：确保模型命名符合项目规范

3. 自动分组
- 功能：根据模型类型自动创建和整理分组
- 使用场景：快速组织和管理模型层级结构

####### 工具栏功能

1. 模型显示控制
- 切换模型显示/隐藏
- 透明度调节
- 线框模式切换

2. LOD选择工具
- LOD级别快速切换
- 多级别对比视图
- 模型细节程度预览

3. 辅助功能
- 模型分离与合并
- 顶点/面数统计
- 模型检查与修复

####### 右侧工具面板

1. 添加功能
- 为每个模型类别提供快速添加功能
- 支持拖拽导入
- 批量导入支持

2. 模型属性编辑
- 材质分配
- UV设置
- 变形器设置

3. 高级功能
- 模型优化建议
- LOD自动生成
- 网格简化工具

####### 注意事项

1. 模型命名规则
- 所有模型必须遵循标准命名规范
- LOD0级别模型名称前需添加"*"标记
- 确保命名无特殊字符

2. 模型层级要求
- 保持正确的层级关系
- 避免深层嵌套
- 确保正确的父子关系

3. 性能优化建议
- 根据实际需求选择合适的LOD级别
- 注意模型面数控制
- 合理使用材质和贴图

###### 2. 绑定视图 (Rigging)

####### DNA预设浏览器

- 预设角色图标矩阵 (6x6网格)
- 缩放控制滑块 (默认90)
- 导入/导出设置按钮

####### 资产设置

- 项目路径设置
- 预设文件选择
- 数据分层选项
  - 行为（包括描述和定义）
  - 覆盖表情选项
- 描述设置：
  - 名称：Archetype
  - 原型：其他
  - 性别：女性
  - 年龄：24
  - 变换单位：厘米
  - 旋转单位：角度
  - 向上轴标：Z轴向上
  - LOD计数：8

###### 3. 行为视图 (Behaviour)

####### Raw Control [814/814]

- 搜索过滤
- BlendShape列表
- 数值调节 (0.010)
- 过滤按钮组 (全部/2/3/4/5/6)
- 范围控制

####### Related Blend Shapes [858/858]

- 关联BlendShape列表
- 数值调节 (0.000)
- 操作按钮组：
  - 翻转目标
  - 镜像目标
  - 查找翻转目标
  - 添加混合目标
  - 删除混合目标
  - 批量混合目标
- 功能按钮组：
  - PSD
  - BSE
  - KEY
  - MIR
  - ARK
  - CTR

###### 4. 定义视图 (Definition)

####### LODs列表

- LOD 0-7
- Define Joint For LOD

####### Meshes [010/54]

- head_lod0_mesh (000)
- teeth_lod0_mesh (001)
- saliva_lod0_mesh (002)
- eyeLeft_lod0_mesh (003)
- eyeRight_lod0_mesh (004)
- eyeshell_lod0_mesh (005)
- eyelashes_lod0_mesh (006)
- eyeEdge_lod0_mesh (007)
- Create Geometry 按钮

####### Joints [840/870]

- FACIAL_C_NeckB         Group: 001
- FACIAL_L_NeckB1        Group: 002
- FACIAL_R_NeckB1        Group: 003

- FACIAL_L_NeckB2        Group: 002
- FACIAL_R_NeckB2        Group: 003
- FACIAL_C12PV_NeckB1    Group: 001

####### Blend Shapes [782/782]

- brow_down_L            000
- brow_down_R            001
- brow_lateral_L         002

- brow_lateral_R         003
- brow_raiseIn_L         004
- brow_raiseIn_R         005

####### AnimatedMap [082/82]

- head_cm2_color.head_wm2.browsDown  000
- head_cm2_color.head_wm2.browsDown  001
- head_cm2_color.head_wm2.browsLate  002

- head_cm2_color.head_wm2.browsLate  003
- head_cm1_color.head_wm1.browsRais  004
- head_cm1_color.head_wm1.browsRais  005

####### 操作区域

- Write：
  - Write Neutral Pose Joint Position
  - Write Geometry
  - Write Skin Weights
  - Write Blend Shapes Targets
- Create：
  - Create Blend Shapes For Mesh
  - Bind Skin For Mesh
  - Unbind Skin For Mesh
- Tools：
  - New Neutral Joint Transform
  - Quickly Create Presets