Metahuman_DNA_Calibration/docs/dna_viewer_api_mesh_utilities.md

Mesh Utilities

The purpose of the following methods is to provide:

• a simple mechanism for building meshes from a given DNA file path
• return and print information about the meshes contained in the DNA file

Importing

from dna_viewer import build_meshes, create_build_options, #get_mesh_index, get_mesh_lods, get_mesh_names, print_meshes, print_mesh_indices_containing_string

DNA_PATH_ADA = f"{ROOT_DIR}/data/dna/Ada.dna"
DNA_PATH_TARO = f"{ROOT_DIR}/data/dna/Taro.dna"

Create build options (create_build_options)

Used to create a configuration object that will be used in the mesh building process.

build_options = create_build_options(
    add_joints=True,
    add_normals=False,
    add_blend_shapes=False,
    add_skin=False,
    add_ctrl_attributes_on_root_joint=False,
    add_animated_map_attributes_on_root_joint=False
)

This uses the following parameters:

• add_joints: bool - A flag representing if joints should be added, defaults to False.
• add_normals: bool - A flag representing if normals from the DNA file should be added, defaults to False.
• add_blend_shapes: bool - A flag representing if blendshapes should be added, defaults to False.
• add_skin: bool - A flag representing if skin clusters should be added, defaults to False.
• add_ctrl_attributes_on_root_joint: bool - A flag representing if control attributes should be added to the root joint as attributes, defaults to False. They are used as animation curves for Rig Logic inputs in the engine.
• add_animated_map_attributes_on_root_joint: bool - A flag representing if animated map attributes should be added to the root joint as attributes, defaults to False. They are used as animation curves for animated maps in the engine.

IMPORTANT: Some combinations of flag values can lead to an unusable rig or disable some features!

Building the meshes (build_meshes)

Used for building rig elements (joints, meshes, blendshapes and skin clusters) without Rig Logic. It returns long names of meshes that have been added to the scene.

mesh_names = build_meshes(
    dna=dna_ada,
    options=build_options,
    group_by_lod=True,
    lod_list=[0, 1],
    mesh_list=[38],
    create_new_scene=True
)

This uses the following parameters:

• dna: DNA - Instance of DNA got with load_dna.
• lod_list: List[int] - A list of LODs to build all meshes for.
• mesh_list: List[int] - A list of mesh indices to build.
• group_by_lod: bool - A flag representing if the built meshes should be added to a MetaHuman group hierarchy in the scene, defaults to False. If the value is False, all created rig elements will be added to the root of the scene.
• options: BuildOptions - Sets the build options.
• create_new_scene: bool - If True, a new scene will be opened before creating rig elements. Defaults to False.

If lod_list and mesh_list are not set, all the meshes will be built.

The method can also be called with only a DNA file path:

mesh_names = build_meshes(dna=dna_ada)

Which defaults to adding all the meshes within the DNA file.

Getting the mesh index for a given string contained in the mesh name and the LOD (get_mesh_index)

Returns the mesh index of the mesh that contains the search string. If multiple matches are found, returns the first one.

mesh_id = get_mesh_index("eye", 0, dna_ada)

This uses the following parameters:

• mesh_name: str - A search string used for getting the mesh index of the mesh name that contains it.
• lod: int - The LOD where the mesh is searched for.
• dna: DNA - Instance of DNA got with load_dna. an exception is raised.

Getting a list of all mesh names (get_mesh_names))

Returns a list of all the mesh names in the DNA.

mesh_names = get_mesh_names(dna_ada)

This uses the following parameters:

• dna: DNA - Instance of DNA got with load_dna. an exception is raised.

Getting a list of mesh indices organized per LODs (get_mesh_lods)

Returns a list of mesh indices grouped by the LOD number.

mesh_indices_by_lod = get_mesh_lods(dna_ada)

This uses the following parameters:

• dna: DNA - Instance of DNA got with load_dna.

Printing all meshes (print_meshes)

Prints the mesh indices and names grouped by LODs.

print_meshes(dna_ada)

This uses the following parameters:

• dna: DNA - Instance of DNA got with load_dna.

Print all mesh indices with names containing the search string (print_mesh_indices_containing_string)

Prints all the meshes and their indices which have names that contain the given search string in a given LOD.

print_mesh_indices_containing_string("eye", 3, dna_ada)

Example

Important: The setup code provided above needs to be executed before running this example.

from dna_viewer import build_meshes, create_build_options
from dna_viewer import print_meshes
from dna_viewer import load_dna

# Sets DNA file path
DNA_PATH_ADA = f"{ROOT_DIR}/data/dna/Ada.dna"
# Prints the mesh ids and names grouped by lods
dna_ada = load_dna(DNA_PATH_ADA)
print_meshes(dna_ada)

# Starts the mesh build process with all the default values
build_meshes(dna_path=dna_ada)

# Creates the options to be passed in `build_meshes`
build_options = create_build_options(
    add_joints=True,
    add_normals=True,
    add_blend_shapes=True,
    add_skin=True,
    add_ctrl_attributes_on_root_joint=True,
    add_animated_map_attributes_on_root_joint=True
)

# Starts the mesh building process with the provided parameters
# In this case it will create every mesh contained in LODs 0 and 1,
# it also adds the mesh with the mesh index value of 38
build_meshes(
    dna=dna_ada,
    options=build_options,
    group_by_lod=True,
    lod_list=[0, 1],
    mesh_list=[38],
    create_new_scene=True
)