Metahuman_DNA_Calibration/docs/dna_viewer_api_build_meshes.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 DNA, Config, build_meshes
```

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

## Create Config Instance([`Config`](../dna_viewer/builder/config.py#35))
Create a configuration object that will be used in the mesh building process.

```
config = Config(
    add_joints=True,
    add_blend_shapes=True,
    add_skin_cluster=True,
    add_ctrl_attributes_on_root_joint=True,
    add_animated_map_attributes_on_root_joint=True,
    lod_filter=[0, 1],
    mesh_filter=["head"],
)
```

These are just some attributes of `Config` class:
- `add_joints: bool` - A flag representing if joints should be added, defaults to `True`.
- `add_blend_shapes: bool` - A flag representing if blendshapes should be added, defaults to `True`.
- `add_skin_cluster: bool` - A flag representing if skin clusters should be added, defaults to `True`.
- `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 `True`. 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`](../dna_viewer/api.py#L26))

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.

```
config = Config(
    add_joints=True,
    add_blend_shapes=True,
    add_skin_cluster=True,
    add_ctrl_attributes_on_root_joint=True,
    add_animated_map_attributes_on_root_joint=True,
    lod_filter=[0, 1],
    mesh_filter=["head"],
)
mesh_names = build_meshes(
    dna=dna_ada,
    config=config
)
```


This uses the following parameters:
- `dna: DNA` - Instance of DNA got with `DNA`.
- `config: Config` - Instance of configuration.

```
mesh_names = build_meshes(dna=dna_ada)
```

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



### Example

**Important**: The [environment setup](dna_viewer_api.md#environment-setup) provided above needs to be executed before running this example.

```
from dna_viewer import DNA, Config, build_meshes

# if you use Maya, use absolute path
ROOT_DIR = f"{ospath.dirname(ospath.abspath(__file__))}/..".replace("\\", "/")
# Sets DNA file path
DNA_PATH_ADA = f"{ROOT_DIR}/data/dna_files/Ada.dna"
dna_ada = DNA(DNA_PATH_ADA)

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

# Creates the options to be passed in `build_meshes`
config = Config(
    add_joints=True,
    add_blend_shapes=True,
    add_skin_cluster=True,
    add_ctrl_attributes_on_root_joint=True,
    add_animated_map_attributes_on_root_joint=True,
    lod_filter=[0, 1],
    mesh_filter=["head"],
)

# Starts the mesh building process with the provided parameters
# In this case it will create every mesh contained in LODs 0 and 1 with 'head` in it's name,
build_meshes(
    dna=dna_ada,
    config=config,
)
```