ProcessSettings
human/process/process.pyProcesses the human for export, as the Process tab does, or step by step.
run does everything the Process tab does, from an ExportSettings:
settings = ExportSettings.from_recipe("unity")
settings.output.folder = "/path/to/project/Assets/Characters"
result = human.process.run(settings)
print(result.files)
The other methods are the single steps of run, which change this human in
place, so call them on a human.duplicate(). They take the section of the
settings they are about, or plain arguments. run does them in this order,
which the steps depend on:
1. `set_shape_keys`, so the other steps only carry the keys that stay
2. `convert_to_haircards`
3. `convert_to_game_eyes` and `lod.set_teeth_lod`, before baking, as
they change the materials
4. `bake_textures`, before the meshes are reduced
5. `set_quality` (or `lod.set_body_lod` and `lod.set_clothing_lod`)
6. `remove_hidden_skin`
7. `set_t_pose_as_rest` and `convert_to_game_rig`
8. `apply_names`
9. `prepare_clips`, once the skeleton is final
10. `human.export.write`, or `mark_as_processed` to keep it in the file
The steps that change the human for good refuse to run twice, see the
has_* and was_* properties.
| Attributes | ||
|---|---|---|
| baking | BakeSettings | The baking API of earlier versions, see `bake_textures`. |
| lod | LodSettings | Gives access to the LOD settings. |
| settings | Optional[ExportSettings] | The settings a processed human was made with, None for other humans. |
| has_haircards | bool | Checks if haircards are present. |
| was_baked | bool | Checks if materials were baked. |
| is_lod | bool | Checks if the body of the human has a lower level of detail. |
| has_game_eyes | bool | Checks if the eyes were converted to single layer eyes. |
| has_t_pose_rest | bool | Checks if the T-pose was baked into the rest pose. |
| has_game_rig | bool | Checks if the rig was converted to a game engine skeleton. |
| game_rig_preset | Optional[str] | The preset the rig was converted with, None if it has no game rig. |
| is_processed | bool | Checks if this human is a frozen result of the process system. |
| Methods | ||
| preflight() | Preflight | Checks what `run` with these settings would complain about. |
| run() | ExportResult | Processes this human by the settings, as the Process tab does. |
| run_steps() | Steps[ExportResult] | The work of `run` as resumable steps, see `HumGen3D.common.progress`. |
| set_shape_keys() | Decides which shape keys stay on the human, per group of keys. | |
| shape_key_options() | Dict[str, List[str]] | The keys `set_shape_keys` can keep, per group, by display name. |
| convert_to_haircards() | List[bpy.types.Object] | Replaces every particle hair system of this human by hair cards. |
| bake_textures() | List[bpy.types.Image] | Bakes every material of this human to textures and replaces it. |
| share_textures() | Gives this human the baked materials of another, per part. | |
| convert_to_game_eyes() | Replaces the layered eyes by single layer eyes for game engines. | |
| set_quality() | Reduces the meshes of this human to the detail of a LOD level. | |
| remove_hidden_skin() | int | Deletes the vertices of the body that the clothing hides. |
| apply_modifiers() | Applies modifiers to the meshes of this human, keeping the shape keys. | |
| set_t_pose_as_rest() | Bakes the T-pose into the rest pose of the meshes and armature. | |
| convert_to_game_rig() | Converts the rig to a skeleton for game engines. | |
| apply_names() | Names the objects, meshes, materials and images by a naming scheme. | |
| prepare_clips() | List[bpy.types.Action] | Gives this human its own animation clips, fitted to its skeleton. |
| merge_levels() | Puts the meshes of other LOD levels under the skeleton of this human. | |
| mark_as_processed() | Marks this human as the frozen, processed result of another human. | |
Attributes
human.process.baking: BakeSettingsread-only
sourceThe baking API of earlier versions, see bake_textures.
human.process.lod: LodSettingsread-only
sourceGives access to the LOD settings.
human.process.settings: Optional[ExportSettings]read-only
sourceThe settings a processed human was made with, None for other humans.
human.process.has_haircards: boolread-only
sourceChecks if haircards are present.
Checks if materials were baked.
Checks if the body of the human has a lower level of detail.
human.process.has_game_eyes: boolread-only
sourceChecks if the eyes were converted to single layer eyes.
human.process.has_t_pose_rest: boolread-only
sourceChecks if the T-pose was baked into the rest pose.
human.process.has_game_rig: boolread-only
sourceChecks if the rig was converted to a game engine skeleton.
human.process.game_rig_preset: Optional[str]read-only
sourceThe preset the rig was converted with, None if it has no game rig.
human.process.is_processed: boolread-only
sourceChecks if this human is a frozen result of the process system.
Methods
human.process.preflight(settings: ExportSettings, context: C = None) → Preflight
sourceChecks what run with these settings would complain about.
| Parameter | Type | Description |
|---|---|---|
| settings | ExportSettings | The settings to check. |
| context | C default None | Blender context. bpy.context if not provided. |
Returns Preflight — Errors that stop the run and warnings that don't.
human.process.run(settings: ExportSettings, context: C = None, progress: Optional[ProgressCallback] = None) → ExportResult
sourceProcesses this human by the settings, as the Process tab does.
This human is not changed. Every LOD level of the settings becomes a processed duplicate, which is added to the file or written to the files of the output format and removed again.
| Parameter | Type | Description |
|---|---|---|
| settings | ExportSettings | What to make, see `ExportSettings.from_recipe`. |
| context | C default None | Blender context. bpy.context if not provided. |
| progress | Optional[ProgressCallback] default None | Called with the fraction done. |
Returns ExportResult — The humans added to the file or the files written, with warnings and triangle counts.
Raises HumGenException — If the preflight finds an error or a step fails.
human.process.run_steps(settings: ExportSettings, context: C = None) → Steps[ExportResult]
sourceThe work of run as resumable steps, see HumGen3D.common.progress.
| Parameter | Type | Description |
|---|---|---|
| settings | ExportSettings | — |
| context | C default None | — |
Returns Steps[ExportResult]
human.process.set_shape_keys(settings: Optional[ShapeKeySettings] = None, level: int = 0, face_rig: KeyAction = 'keep', expressions: KeyAction = 'keep', correctives: KeyAction = 'keep', body: KeyAction = 'bake', face: KeyAction = 'bake', age: KeyAction = 'bake', keep: Optional[KeepSelection] = None, context: C = None)
sourceDecides which shape keys stay on the human, per group of keys.
Each group is kept as shape keys, baked into the mesh at its current value or removed. Keeping livekeys converts them to shape keys, so for example the body sliders can be exported as blend shapes. The livekeys and the gender key are always baked afterwards, as is the fit of the clothing. Kept keys that bones drive, the face rig and the correctives, need their drivers reconnected after exporting.
| Parameter | Type | Description |
|---|---|---|
| settings | Optional[ShapeKeySettings] default None | The actions as a recipe holds them. The other arguments are ignored when given. |
| level | int default 0 | The LOD level this human is, with `settings` only. With `ShapeKeySettings.lod0_only` the lower levels keep no keys. |
| face_rig | KeyAction default 'keep' | "keep" loads the FACS face rig if the human has none yet, "remove" removes it. Baking is not possible. |
| expressions | KeyAction default 'keep' | The 1-click expressions. |
| correctives | KeyAction default 'keep' | Keys driven by bones that fix the joints and the eyelids, also on the clothing. |
| body | KeyAction default 'bake' | The body proportion sliders, including the muscles. |
| face | KeyAction default 'bake' | The face proportion sliders, face presets and eyes. |
| age | KeyAction default 'bake' | The age sliders. |
| keep | Optional[KeepSelection] default None | Per group the names of the keys to keep, see `shape_key_options`. Missing groups keep all. |
| context | C default None | Blender context. bpy.context if not provided. |
Raises ValueError — If an action is not possible for a group.
human.process.shape_key_options(context: C = None) → Dict[str, List[str]]
sourceThe keys set_shape_keys can keep, per group, by display name.
The face rig and the expressions list everything in the library, the
other groups what this human has. Use a subset as the keep argument
or ShapeKeySettings.keep.
| Parameter | Type | Description |
|---|---|---|
| context | C default None | Blender context. bpy.context if not provided. |
Returns Dict[str, List[str]]
human.process.convert_to_haircards(quality: Literal['ultra', 'high', 'medium', 'low', 'haircap_only'] = 'high', context: C = None) → List[bpy.types.Object]
sourceReplaces every particle hair system of this human by hair cards.
The hair, eyebrows, eyelashes and facial hair each become a mesh object
with a haircap and cards, skinned to the rig, see
human.hair.regular_hair.convert_to_haircards for one of them. The
particle systems are removed afterwards, as no file format carries them.
| Parameter | Type | Description |
|---|---|---|
| quality | Literal['ultra', 'high', 'medium', 'low', 'haircap_only'] default 'high' | Triangle budget of the cards, see `QualitySettings.haircards`. |
| context | C default None | Blender context. bpy.context if not provided. |
Returns List[bpy.types.Object] — List[bpy.types.Object]: The hair card objects that were made.
Raises HumGenException — If the human has hair cards already.
human.process.bake_textures(settings: Optional[TextureBakeSettings] = None, folder: Optional[str] = None, output: Optional[OutputSettings] = None, level: int = 0, levels: int = 1, only_sets: Optional[Iterable[str]] = None, context: C = None) → List[bpy.types.Image]
sourceBakes every material of this human to textures and replaces it.
The skin, hair and eye materials are node trees exporters can't read, so every material becomes a Principled BSDF with image nodes, with the maps packed and flipped as the settings ask. The materials are copied first, so a human this one was duplicated from keeps its own.
| Parameter | Type | Description |
|---|---|---|
| settings | Optional[TextureBakeSettings] default None | Passes, resolution, packing, normal map direction and samples. Separate maps at 2k by default. |
| folder | Optional[str] default None | Folder to write the images to, None packs them in the blend file. |
| output | Optional[OutputSettings] default None | Naming scheme and name of the images and materials, see `apply_names`. The plain scheme with the name of the human by default. |
| level | int default 0 | LOD level of this human, for the names. |
| levels | int default 1 | Number of LOD levels, for the names. |
| only_sets | Optional[Iterable[str]] default None | Bake only these texture sets of `TEXTURE_SETS`, for a level that shares the others, see `share_textures`. |
| context | C default None | Blender context. bpy.context if not provided. |
Returns List[bpy.types.Image] — List[bpy.types.Image]: The images of the new materials.
Raises HumGenException — If the materials were baked already.
human.process.convert_to_game_eyes(detail: Literal['high', 'medium', 'low'] = 'medium')
sourceReplaces the layered eyes by single layer eyes for game engines.
Only the front of the cornea is kept, with the eye color as opaque material on it. Applies the shape keys of the eyes, so changing the height or proportions won't work on this human anymore.
| Parameter | Type | Description |
|---|---|---|
| detail | Literal['high', 'medium', 'low'] default 'medium' | Resolution of the eye mesh. Medium has a quarter of the triangles of high, low about a sixteenth. |
human.process.set_quality(quality: QualitySettings, meshes: Optional[MeshSettings] = None, context: C = None)
sourceReduces the meshes of this human to the detail of a LOD level.
Converts the eyes, decimates the teeth and the clothing and dissolves
edges of the body, as QualitySettings asks. Hair cards and bones per
vertex are not part of it, see convert_to_haircards and
convert_to_game_rig. Meshes that have their detail already are skipped.
| Parameter | Type | Description |
|---|---|---|
| quality | QualitySettings | Detail per mesh, see `QualitySettings.from_tier`. |
| meshes | Optional[MeshSettings] default None | Which modifiers of the clothing to remove and whether to remove the skin under it. Defaults apply. |
| context | C default None | Blender context. bpy.context if not provided. |
human.process.apply_modifiers(modifier_types: Iterable[str], objects: Optional[Iterable[bpy.types.Object]] = None, apply_hidden: bool = False, context: C = None)
sourceApplies modifiers to the meshes of this human, keeping the shape keys.
Blender refuses to apply a modifier to a mesh with shape keys, this applies it to every key. For scripts and anything the other steps don't cover; particle systems and decimate modifiers are never applied.
| Parameter | Type | Description |
|---|---|---|
| modifier_types | Iterable[str] | Types to apply, like "SUBSURF" or "SOLIDIFY". |
| objects | Optional[Iterable[bpy.types.Object]] default None | Meshes to apply to, every mesh of the human when None. |
| apply_hidden | bool default False | Also apply modifiers hidden in the viewport. |
| context | C default None | Blender context. bpy.context if not provided. |
human.process.set_t_pose_as_rest(context: C = None)
sourceBakes the T-pose into the rest pose of the meshes and armature.
Discards the current pose and removes the shoulder side raise corrective shape keys. Features that rely on the A-pose rest pose, like changing the pose, height, proportions or clothing, won't work on this human anymore.
| Parameter | Type | Description |
|---|---|---|
| context | C default None | The Blender context. Defaults to None. |
Raises HumGenException — If the rest pose is the T-pose already, or the human is a Rigify or legacy human.
human.process.convert_to_game_rig(preset: str = 'generic_a', keep_eyes: bool = True, keep_jaw: bool = True, keep_breasts: bool = True, keep_metacarpals: bool = False, max_influences: int = 4, root_bone: Optional[bool] = None, root_bone_name: Optional[str] = None, names_file: Optional[str] = None, settings: Optional[SkeletonSettings] = None, context: C = None)
sourceConverts the rig to a skeleton for game engines.
Removes the bones that deform nothing, like the face rig controls and the
eye targets, and bakes the shape keys they drove at their current value.
Merges the weights of the bones that are not kept into their parents, adds
a root bone at the origin, bakes the constraints into the pose, removes the
vertex groups that are neither bones nor used by a modifier, limits the
number of bones per vertex and renames the bones for the preset. The face
rig, poses and animations of Human Generator won't work on this human
anymore. Combine with set_t_pose_as_rest for the presets that expect a
T-pose, which happens by itself when settings ask for it.
| Parameter | Type | Description |
|---|---|---|
| preset | str default 'generic_a' | Engine to name the bones for: "generic_a" and "generic_t" keep the Human Generator names ("humgen" picks one by the rest pose), "humanoid" uses the names of Unity, Godot and VRM, "unreal" the Mannequin names, "mixamo" the Mixamo names and "custom" the names of names_file. The rest pose of the preset is not applied here, see set_t_pose_as_rest. |
| keep_eyes | bool default True | Keep the eye bones, otherwise the eyes follow the head. |
| keep_jaw | bool default True | Keep the jaw bones that move the teeth. |
| keep_breasts | bool default True | Keep the breast bones. |
| keep_metacarpals | bool default False | Keep the palm bones between hand and fingers. |
| max_influences | int default 4 | Maximum number of bones per vertex, 0 for no limit. Also with `settings`, as `QualitySettings.bones_per_vertex` holds it per LOD level. |
| root_bone | Optional[bool] default None | Add a root bone at the origin, None uses the choice of the preset. Mixamo has none, the others do. |
| root_bone_name | Optional[str] default None | Name of the root bone, None uses the name of the preset. |
| names_file | Optional[str] default None | JSON file with "names" and "sides" like game_rig_presets.json, for the "custom" preset. |
| settings | Optional[SkeletonSettings] default None | The skeleton as a recipe holds it, replaces the arguments above except max_influences. Its rest pose is applied first when it is the T-pose. |
| context | C default None | Blender context. bpy.context if not provided. |
Raises HumGenException — If the human has a game rig already, or is a Rigify or legacy human.
Raises ValueError — If the preset does not exist.
human.process.apply_names(output: Optional[OutputSettings] = None, level: int = 0, levels: int = 1)
sourceNames the objects, meshes, materials and images by a naming scheme.
A copy of a human has names like "HG_Body.001", which engines show. This names every datablock after the human and its part instead: "Jake_Body", "Jake_Skin" and "Jake_Body_BaseColor", or with the Unreal scheme "SK_Jake_Body", "M_Jake_Skin" and "T_Jake_Body_BC". Unused material slots are removed. Materials shared with another human, like the one this is a duplicate of, are copied first.
| Parameter | Type | Description |
|---|---|---|
| output | Optional[OutputSettings] default None | Scheme, templates and the name, `OutputSettings.name` with "{name}" for the name of the human. The plain scheme with the name of the human by default. |
| level | int default 0 | LOD level of this human, added as "_LOD1" suffix to the meshes when there is more than one level. |
| levels | int default 1 | Number of LOD levels. |
human.process.prepare_clips(settings: Optional[AnimationClipSettings] = None, source: Optional[Human] = None, context: C = None) → List[bpy.types.Action]
sourceGives this human its own animation clips, fitted to its skeleton.
After convert_to_game_rig the actions of the source human no longer
fit: bones are gone or renamed and the rest pose may be the T-pose. The
Human Generator animations are retargeted onto the converted skeleton,
other actions are copied as they are with a warning in the log. The
clips end up as one NLA strip each, so human.export.write(..., animation="strips") writes every clip as a take. Afterwards the clips
are the only animation on this human.
| Parameter | Type | Description |
|---|---|---|
| settings | Optional[AnimationClipSettings] default None | Which clips, from the human or the library, and the root motion. Every clip on the source human by default. |
| source | Optional[Human] default None | The human the clips come from, this human by default. Pass the original when this is its duplicate. |
| context | C default None | Blender context. bpy.context if not provided. |
Returns List[bpy.types.Action] — List[bpy.types.Action]: The clips of this human.
human.process.merge_levels(levels: List[Human])
sourcePuts the meshes of other LOD levels under the skeleton of this human.
For one file with every level. The skeletons have to be identical, which they are when the levels were made from the same source with the same skeleton settings. The rigs of the other levels are removed, so they are no humans afterwards.
| Parameter | Type | Description |
|---|---|---|
| levels | List[Human] | The other levels, in order of detail. |
human.process.mark_as_processed(original_human: Human)
sourceMarks this human as the frozen, processed result of another human.
The Human Generator interface doesn't allow editing processed humans, it refers to the original human instead.
| Parameter | Type | Description |
|---|---|---|
| original_human | Human | The editable human this human was made from. |