DOCSEARCHbyAlgolia
Submit Docs

MetaHuman DNA Calibration

repository·main·Indexed 20 days ago

https://github.com/epicgames/metahuman-dna-calibration

A toolset for inspecting, modifying, and visualizing MetaHuman DNA files. It includes DNACalib for manipulating joints, meshes, blendshapes, and LODs via Python or C++ APIs, and DNAViewer for creating functional rigs for Maya and exporting FBX files. Compatible with MetaHuman characters created in Unreal Engine 5.5 or earlier.

Tokens
27.2K
Snippets
61
Records
115
Agent score
69%

What's inside MetaHuman DNA Calibration

  1. Overview of DNACalib

    main

    DNACalib is a library used for performing modifications on MetaHuman DNA files. It is implemented in C++ and provides a Python wrapper (generated via SWIG). The library can be used via the command line, within Python scripts, or integrated into Autodesk Maya.

    Note: Prebuilt binaries are provided for 64-bit Windows and Linux. Users on other architectures or platforms must build the library from source.

  2. Overview of MetaHuman DNA Calibration tools

    main

    MetaHuman DNA Calibration is a package of tools designed to inspect and modify MetaHuman DNA files. The repository provides two primary tools:

    1. DNACalib: Used for inspecting and modifying DNA files. Capabilities include:

      • Renaming joints, meshes, blendshapes, and animated maps.
      • Removing joints, meshes, and joint animations.
      • Transforming the rig (rotate, scale, translate).
      • Removing LODs.
      • Modifying neutral joint/mesh positions and blendshape delta values.
      • Pruning or removing all blendshape data.
      • Warning: Do not remove or rename the following joints used for head-to-body connection: neck_01, neck_02, and FACIAL_C_FacialRoot.

    2. DNAViewer: Used for:

      • Creating functional rigs for Maya.
      • Exporting FBX files.
      • Reading internal parts of DNA files.

    Compatibility Note: This repository is compatible with MetaHuman characters created in Unreal Engine 5.5 or earlier. For UE 5.6+, use the MetaHuman for Maya plugin available on Fab.

  3. Understand the MetaHuman DNA Calibration components

    main

    The repository consists of two primary, independent components:

    1. dnacalib C++ library: A library used for the manipulation of DNA files.
    2. dna_viewer python code: A tool used to visualize DNA within Autodesk Maya.

    Additional resources include pre-built binaries in /lib, example DNA files and Maya scenes in /data, and Python scripts in /examples for demonstrating usage of both the dna_viewer and the Python wrapper for DNACalib.

  4. Understand MetaHuman DNA Layers

    main

    MetaHuman DNA files organize data into logical layers that form a loose hierarchy. Each subsequent layer relies on data from the layers above it. You can selectively load only specific layers to optimize performance (e.g., loading only the Behavior layer to drive a rig without needing Geometry data).

    Layer Hierarchy & Contents:

    • Descriptor: Basic metadata (Name, Age, Facial archetype, custom key/value pairs).
    • Definition: Static rig data (Names of controls, joints, blend shapes, meshes; Joint hierarchy; Bind pose transformations).
    • Behavior: Dynamic rig data (Control mapping, corrective expressions, joint transformations, blend shape weights).
    • Geometry: Mesh reconstruction data (Mesh structure, skin weights, blend shape target deltas).

  5. How DNA modification works via Commands

    main

    DNA modification in the DNACalib library is performed using a command-based pattern. Each modification is encapsulated in a command object that implements the run(DNACalibDNAReader* output) method.

    To use a command, you typically:

    1. Instantiate the command class.
    2. Configure the modification parameters via the constructor or specific setter methods.
    3. Call run() passing a pointer to a DNACalibDNAReader which represents the DNA to be modified.

    Note: This API documentation currently applies only to C++. There is no Python documentation available.

  6. Understand the DNAViewer folder structure

    main

    The dna_viewer module is organized into three functional sub-packages:

    • builder: Contains builder classes used to configure and construct scenes, configurations, and meshes.
    • dnalib: Provides high-level classes for easier API access to DNA files.
    • ui: Contains the classes required to render and manage the Maya user interface.

  7. Set up DNACalib binaries on Linux

    main

    To use the pre-built DNACalib binaries on Linux, you must create symbolic links for the .so files located in lib/Maya2022/linux to your /usr/lib directory.

    Note: Replace ~/MetaHuman-DNA-Calibration with the actual absolute path to your repository installation.

    sudo ln -s ~/MetaHuman-DNA-Calibration/lib/Maya2022/linux/_py3dna.so /usr/lib/_py3dna.so

sudo ln -s ~/MetaHuman-DNA-Calibration/lib/Maya2022/linux/libdnacalib.so /usr/lib/libdnacalib.so

sudo ln -s ~/MetaHuman-DNA-Calibration/lib/Maya2022/linux/libdnacalib.so.6 /usr/lib/libdnacalib.so.6

sudo ln -s ~/MetaHuman-DNA-Calibration/lib/Maya2022/linux/libembeddedRL4.so /usr/lib/embeddedRL4.mll

sudo ln -s ~/MetaHuman-DNA-Calibration/lib/Maya2022/linux/MayaUERBFPlugin.mll /usr/lib/MayaUERBFPlugin.mll

  11. Set up the environment for dna_viewer

    main

    To import and use dna_viewer in your scripts, you must configure the Python path and environment variables so the interpreter can locate the library and its dependencies.

    If you are running scripts within Maya, ensure ROOT_DIR is set to the absolute path of the repository root instead of using the relative path logic provided below.

    Key steps performed by the setup code:

    1. Determines the correct library directory (LIB_DIR) based on the operating system (win32 or linux).
    2. Appends LIB_DIR to the MAYA_PLUG_IN_PATH environment variable to ensure Maya can find the necessary plugins.
    3. Appends both the repository root and the library directory to sys.path.
    from sys import path as syspath, platform
from os import environ, path as ospath

# Note: If using Maya, replace this with an absolute path to the repo root
ROOT_DIR = fr"{ospath.dirname(ospath.abspath(__file__))}/..".replace("\\", "/") 
ROOT_LIB_DIR = fr"{ROOT_DIR}/lib"
if platform == "win32":
    LIB_DIR = f"{ROOT_LIB_DIR}/windows"
elif platform == "linux":
    LIB_DIR = f"{ROOT_LIB_DIR}/linux"
else:
    raise OSError("OS not supported, please compile dependencies and add value to LIB_DIR")


if "MAYA_PLUG_IN_PATH" in environ:
    separator = ":" if platform == "linux" else ";"
    environ["MAYA_PLUG_IN_PATH"] = separator.join([environ["MAYA_PLUG_IN_PATH"], LIB_DIR])    
else:
    environ["MAYA_PLUG_IN_PATH"] = LIB_DIR

syspath.append(ROOT_DIR)
syspath.append(LIB_DIR)

  12. Change the DNA path in a Maya scene

    main

    If you need to point a Maya scene to a different DNA file, follow these steps in Maya:

    1. Open the Outliner.
    2. Deselect DAG Objects Only in the Outliner settings.
    3. Search for rl4 in the Outliner.
    4. Locate and select the file whose name starts with rl4Embedded_.
    5. Open the Attribute Editor for that selected object.
    6. Locate the Dna File Path attribute and update it with the new path.