Metahuman DNA to OBJ Facial Expression Extractor

The dna_expression_extractor takes a head.dna file as input, reads and evaluates it through Epic's official RigLogic runtime, and exports every control's facial expression, as well as each PSD corrective expression, as a discrete morph target (full blendshape + joint deformation). Alongside the output, a correctives.json file provides the connection logic needed to wire everything back up in the DCC of your choice (Maya, Blender, etc.). A joints.json file is also included, listing the full skeleton hierarchy.

Buy Me a Coffee

If you find this project helpful, buying me a coffee shows your appreciation buymeacoffee.com/SeanNolan

Usage

dna_expression_extractor <file.dna> -o <out_dir> [options]

Argument	Description
<file.dna>	Path to the MetaHuman head.dna file to read. Required, positional.
-o <out_dir>	Directory the OBJs and JSON sidecars are written to. Default: expression_objs.
--mesh <name>	Export only this mesh. Repeatable (pass multiple times for multiple meshes). Default: all meshes at --lod.
--lod <n>	LOD level used for mesh selection and the RigInstance. Default: 0.
--up-axis y|z	Coordinate system for all output: OBJ positions, blendshape deltas, and joint transforms. Default: y.
--list-expressions	Print the raw control list and PSD corrective count, (no export).
--list-meshes	Print the meshes available at --lod, (no export).
--help, -h	Print usage and exit (no export).

Example:

dna_expression_extractor head.dna -o expression_objs

Output

Every run writes into -o <out_dir>:

• base_neutral.obj - neutral base meshes (all if not specified at export time)
• One .obj per raw control (the full pose, blendshape + joint deformation combined) and one isolated-delta .obj per PSD corrective (the combo pose with each contributing single expression subtracted out, then rebased onto neutral, so it imports as a standalone morph target rather than requiring its drivers to already be active).
• correctives.json: units (cm), the coordinate system actually used (up_axis, matching whatever --up-axis resolved to), and the driver → driven wiring for every control and corrective, so combinationShape-style nodes can be reconnected in your DCC.
• joints.json: the full skeleton hierarchy. Each joint lists its name, parent (its actual DNA parent, null for the root), and local translate/rotate (cm / degrees) relative to that parent.

Compatibility

Tested against MetaHuman head.dna files exported from Unreal Engine 5.7. Other 5.x versions producing the same DNA format are expected to work but aren't independently verified.

Building via GitHub Actions

Rather than configuring the build locally, you can trigger .github/workflows/build.yml manually (Actions tab -> "Build" -> "Run workflow"). It's a workflow_dispatch-only job that clones OpenRigLogic, configures and builds on windows-latest, and uploads dna_expression_extractor.exe as a downloadable artifact.

Building from source

1. Install a C++17 compiler

On Windows, install Visual Studio Build Tools (or full Visual Studio) with the "Desktop development with C++" workload checked. This provides the cl.exe compiler and MSBuild that CMake will use in the steps below. Without it, cmake --build fails.

2. Install CMake

Download CMake (3.16 or newer) from cmake.org/download. On Windows, the installer has an option to add CMake to the system PATH for all users or the current user; enable it so cmake is callable from any terminal. If you skip that step, add the CMake bin folder to your PATH manually afterward.

Verify it's on your PATH:

cmake --version

3. Clone this repo

Open a terminal in whatever parent directory you'd like the project to live under, then clone the repo (this creates a new dna_2_obj folder for you):

git clone https://github.com/swnolan/dna_2_obj.git
cd dna_2_obj

4. Get OpenRigLogic

The build depends on Epic's OpenRigLogic repo, the public RigLogic runtime and DNA reader. This is fully public: no Epic Games account, no Unreal Engine EULA, and no GitHub-to-Epic account linking is required. (That's in contrast to pulling RigLogicLib out of the private Unreal Engine source tree, which does require a linked Epic account; this project avoids that path.)

git clone --depth 1 https://github.com/EpicGames/OpenRigLogic.git

Clone it anywhere convenient; you'll pass its path to CMake in the next step. It ships its own CMakeLists.txt and vendors its own CMakeModulesExtra, so no additional module setup is needed.

5. Configure and build

cmake -B build -DRIGLOGIC_DIR=/path/to/OpenRigLogic
cmake --build build --config Release

The built binary always lands at bin/x64/dna_expression_extractor.exe, regardless of the Debug/Release config.

6. Get a head.dna file to test with

You'll need a MetaHuman head.dna file to run the tool against. These are exported from Epic's MetaHuman tooling (MetaHuman Creator or Unreal's MetahumanForMaya); obtaining one does require an Epic Games account, separately from the OpenRigLogic build dependency above.

7. Run it

./bin/x64/dna_expression_extractor.exe path/to/your.dna -o expression_objs

Installing the Maya side as a module

A dna2obj.mod file lets Maya's module system pick up the dna2obj Python package (see python/dna2obj/maya/README.md for what it does) without manually editing PYTHONPATH.

1. Download the dna2obj-maya-module artifact from a build.yml run (Actions tab -> latest "Build" run -> Artifacts) and extract it. You get two items: a dna2obj.mod file and a dna2obj/ folder (bundling python/ and the built bin/x64/dna_expression_extractor.exe).
2. Drag both items into a folder Maya's module system scans, e.g. %USERPROFILE%\Documents\maya\modules.
3. Restart Maya. dna2obj.mod adds dna2obj/python/ to PYTHONPATH so import dna2obj works from the Script Editor.

License

MIT (see LICENSE). This project builds against Epic's OpenRigLogic, also MIT-licensed; it's cloned separately at build time (see above) and isn't vendored in this repo.