MetaFusion/README.md

# MetaHuman DNA 校准
MetaHuman DNA 校准是一组用于处理 MetaHuman DNA 文件的工具，捆绑在一个单独的包中。
[`DNA`](/docs/dna.md#metahuman-dna) 是 [MetaHuman](https://www.unrealengine.com/en-US/metahuman) 身份的一个组成部分。
DNA 文件是使用 [MetaHuman Creator](https://metahuman.unrealengine.com/) 创建，并通过 
[Quixel Bridge](https://docs.metahuman.unrealengine.com/en-US/downloading-metahumans-with-quixel-bridge/) 和 UE5 中的 Bifrost 下载的。

MetaHuman DNA 校准是一组用于处理 MetaHuman DNA 文件的工具，捆绑在一个单独的包中。我们希望分享此代码，以帮助用户自定义 DNA 文件，从而能够更好地将他们创建的角色集成到他们的游戏和体验中。
MetaHuman DNA 校准工具在 GitHub 存储库中提供，地址在此。

# 概述
关于存储库的组织方式的解释，[点击此处](docs/repository_organization.md)。

MetaHuman DNA 校准存储库包含两个不同的工具：
- [DNACalib](docs/dnacalib.md)（及其依赖项）
- [DNAViewer](docs/dna_viewer.md)

## 所需知识
要使用这些工具，您应该熟悉：
- 在 Maya 中的绑定
- Python

## 可选知识
- C++（用于 [DNACalib](docs/dnacalib.md) 及其 [API](docs/dnacalib_api.md)）

## DNACalib
[DNACalib](docs/dnacalib.md) 及其 [API](docs/dnacalib_api.md) 用于检查和修改 DNA 文件。使用 [DNACalib](docs/dnacalib.md)，您可以在 DNA 文件中进行以下更改：
- 重命名关节、网格、混合形状和/或动画映射。
- 删除关节、网格和/或关节动画。
- 旋转、缩放和平移装备。
- 删除 LOD。
- 更改中立关节位置、中立网格位置和混合形状增量值。
- 修剪混合形状。
- 删除所有混合形状数据。

MetaHuman DNA 文件格式的概述可以在 [`这里`](/docs/dna.md) 找到。

**注意**：DNACalib 库允许删除和重命名任何关节。然而，以下关节用于连接头部和身体，不应被删除或重命名：neck_01、neck_02、FACIAL_C_FacialRoot。

## 外部软件依赖项
DNACalib 的 Python 包装器是针对 Python 3.7 和 3.9 编译的。Windows 和 Linux（均为 64 位）的预编译二进制文件是存储库的一部分。
如果您使用的是不同版本的 Python，则必须重新编译。任何 Python 3 版本都应该可以。
如果用户具有不同的平台或架构，则必须编译库及其依赖项。

**重要**
DNA 文件作为 [LFS（大文件存储）](https://git-lfs.github.com/) 文件存储。如果安装并配置了 git-lfs 以供使用，它们将与其余代码一起下载。如果您未使用 git-lfs，则必须手动下载 DNA 文件。

更多信息可以在 [这里](docs/faq.md#fix--runtimeerror--error-loading-dna--dna-signature-mismatched-expected-dna-got-ver-) 找到。

**警告**：
不支持 Python 2。

DNACalib 可以在 C++ 项目中作为 C++ 库使用。

DNACalib Python 包装器可以在 Python 3.7 和 3.9 中使用，`mayapy`（与 Maya 一起提供的 Python 解释器）与 Maya 一起使用。
支持的 Maya 版本为 2022 和 2023。

注意：Maya 2022 与 Python 3.7 捆绑，Maya 2023 与 Python 3.9 捆绑。

## 环境设置

为了在您的脚本中使用 MetaHuman DNA 校准，您需要：
- 安装 Python3，参见 [注意事项](README.md#external-software-dependencies)，
- 将 MetaHuman DNA 校准的位置添加到 `MAYA_MODULE_PATH` 系统变量中（如果您想在 Maya 中使用 MetaHuman DNA 校准）

如果您计划从命令行运行脚本：

- 对于 Maya 的解释器（mayapy），您将必须使用以下代码初始化 maya：

```python
import maya.standalone 
maya.standalone.initialize()
```
- 对于 python 解释器，您将必须在脚本顶部添加以下内容： 
```python
from os import path as ospath
from sys import path as syspath
from sys import platform

ROOT_DIR = f"{ospath.dirname(ospath.abspath(__file__))}/..".replace("\\", "/")
MAYA_VERSION = "2022"  # 或 2023
ROOT_LIB_DIR = f"{ROOT_DIR}/lib/Maya{MAYA_VERSION}"
if platform == "win32":
    LIB_DIR = f"{ROOT_LIB_DIR}/windows"
elif platform == "linux":
    LIB_DIR = f"{ROOT_LIB_DIR}/linux"
else:
    raise OSError(
        "操作系统不支持，请编译依赖项并为 LIB_DIR 添加值"
    )

# 将目录添加到路径
syspath.insert(0, ROOT_DIR)
syspath.insert(0, LIB_DIR)
```

注意：
如果在 Linux 上运行，请确保在运行示例之前将 `LD_LIBRARY_PATH` 附加到 `lib/Maya2022/linux` 或 `lib/Maya2023/linux` 目录的绝对路径：
 - `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<路径到 lib-linux 目录>`

## DNAViewer
使用 DNAViewer，您可以：
- 为 Maya 创建功能性装备。
- 导出 FBX 文件。
- 读取 DNA 文件的内部部分。

DNAViewer 可以在 `mayapy`（与 Maya 一起提供的 Python 解释器）或 Maya 2022 中使用，除了 [从 Maya 场景传播更改到 dna](/examples/dna_viewer_grab_changes_from_scene_and_propagate_to_dna.py)，它只能在 Maya 中使用。

# 示例
提供了几个 Python 示例作为参考，可以在 **examples'** 文件夹中找到：
- [展示一些命令](/examples/dnacalib_demo.py)
- [重命名关节](/examples/dnacalib_rename_joint_demo.py)
- [从头创建一个小的 DNA](/examples/dna_demo.py)
- [读取二进制 DNA 并以人类可读格式写入](/examples/dna_binary_to_json_demo.py)
- [通过提取特定 LOD 从现有 DNA 创建新的 DNA](/examples/dnacalib_lod_demo.py)
- [删除关节](/examples/dnacalib_remove_joint.py)
- [清除混合形状数据](/examples/dnacalib_clear_blend_shapes.py)
- [从中立网格中减去值](/examples/dnacalib_neutral_mesh_subtract.py)
- [Maya 中的简单 UI](examples/dna_viewer_run_in_maya.py) 及其一些 [文档](docs/dna_viewer.md#usage-in-maya)
- [生成装备](/examples/dna_viewer_build_rig.py)
- [按 LOD 导出 FBX](/examples/dna_viewer_export_fbx.py)
- [从 Maya 场景传播更改到 dna](/examples/dna_viewer_grab_changes_from_scene_and_propagate_to_dna.py)
- [生成带有纹理的面部装备](/examples/dna_viewer_build_rig_with_textures.py)

注意：示例分为三组：DNA、DNACalib 和 DNAViewer。这些名称作为前缀嵌入：dna_、dnacalib_ 和 dna_viewer_。

## 示例 DNA 文件
[两个演示 DNA 文件](data/dna_files) 提供以便更轻松地测试此工具。任何使用 [MetaHumanCreator](https://www.unrealengine.com/en-US/metahuman) 生成的 DNA 都应该可以工作。

MHC 2023 春季发布对装备定义进行了更改（关节数量增加以及表达式数量增加）。
为了适应这些更改，我们在 `/data/mh4` 文件夹中向存储库添加了几个文件：新的 [gui 场景](/data/mh4/gui.ma)、更新的 [组装脚本](/data/mh4/additional_assemble_script.py) 和 Ada 的示例 [DNA 文件](data/mh4/dna_files/Ada.dna)。
如果用户想要切换并使用这个新的装备版本，则有必要在他们的脚本中更新路径：
```python
GUI = f"{DATA_DIR}/mh4/gui.ma"
ADDITIONAL_ASSEMBLE_SCRIPT = f"{DATA_DIR}/mh4/additional_assemble_script.py"
```
如果角色 DNA 是从 [Quixel Bridge](https://quixel.com/bridge) 下载的，并且我们不确定使用的是哪个装备定义，可以使用以下代码进行检查：
```python
from dna import (
    BinaryStreamReader,
    DataLayer_All,
    FileStream,
    Status,
)

def load_dna_reader(dna_file):
    stream = FileStream(
        dna_file, FileStream.AccessMode_Read, FileStream.OpenMode_Binary
    )
    reader = BinaryStreamReader(stream, DataLayer_All)
    reader.read()
    if not Status.isOk():
        status = Status.get()
        raise RuntimeError(f"错误加载 DNA: {status.message}")
    return reader

角色_dna = "路径到/角色.dna"
reader = load_dna_reader(角色_dna)
if reader.getDBName() == "MH.4":
  print("使用 mh4 文件夹")
elif reader.getDBName() == "DHI":
  print("使用 data 文件夹")
else:
  print("不支持的装备定义!")
```

# 注意
如果用户在 Maya 中运行示例，`ROOT_DIR` 的值应该更改并且必须使用绝对路径，
例如在 Windows 中为 `c:/MetaHuman-DNA-Calibration` 或在 Linux 中为 `/home/user/MetaHuman-DNA-Calibration`。重要：使用 `/`（正斜杠），Maya 在路径中使用正斜杠。

更多规格请参阅 [常见问题解答指南](docs/faq.md)。

# 许可证
MetaHuman DNA 校准随 [许可证](LICENSE) 发布。