# AnimationSettings

> Human Generator for Blender documentation. Web version: https://humgen3d.com/docs/api/animationsettings

Reached as: `human.animation`

Inherits from: [PreviewCollectionContent](https://humgen3d.com/docs/api/previewcollectioncontent)

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L43

Class for applying animations from the Human Generator library.

Animations are stored as rig independent clips and retargeted to the rig of this
human when set, see retarget.py. The result is a normal Blender action on the
rig, which can be edited like any other animation. Animations can also be added
as strips in the NLA editor, to chain or layer them.

When the human changes shape the actions are retargeted again, in place: only
the channels of the animated bones are written again, other channels, the name
and fake user of the action and the NLA strips using it are kept.

## Attributes

### action

```python
human.animation.action: Optional[bpy.types.Action]
```

*read-only*

The active action created by Human Generator on the rig, if any.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L62

### strips

```python
human.animation.strips: list[bpy.types.NlaStrip]
```

*read-only*

NLA strips on the rig with an animation created by Human Generator.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L77

### actions

```python
human.animation.actions: list[bpy.types.Action]
```

*read-only*

All actions created by Human Generator on the rig, active and in strips.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L90

### is_active

```python
human.animation.is_active: bool
```

*read-only*

True if a Human Generator animation is on this human, active or in NLA.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L99

### loop

```python
human.animation.loop: bool
```

*read-only*

True if the active animation repeats outside its frame range.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L104

### finger_curl

```python
human.animation.finger_curl: float
```

*read-only*

Blend of the fingers between the rest pose (0) and the animation (1).

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L110

### frame_count

```python
human.animation.frame_count: int
```

*read-only*

Number of keyed frames of the active animation, 0 if there is none.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L118

## Methods

### set()

```python
human.animation.set(preset: str, context: C = None, loop: Optional[bool] = None, set_frame_range: bool = True, finger_curl: float = DEFAULT_FINGER_CURL, as_strip: bool = False, frame_start: Optional[int] = None) -> Optional[bpy.types.Action]
```

Applies an animation from the Human Generator library to this human.

By default the animation becomes the active action of the rig, replacing
the active Human Generator animation set before, and the pose of the body.
The pose of the face rig is kept. Keys are placed on whole scene frames,
resampled if the frame rate of the clip differs from the scene.

With `as_strip` the animation is added as a strip in the NLA editor instead,
after the last strip added this way. An active Human Generator animation
is pushed down to a strip first, so the new one is visible.

Parameters:
- `preset` (str): Name of the animation to set, you can get options from the `get_options` method.
- `context` (C, default None): Context to use. Defaults to None.
- `loop` (Optional[bool], default None): Repeat the animation outside its frame range. Defaults to the setting of the clip, True for cyclic animations.
- `set_frame_range` (bool, default True): Set the frame range of the scene to the animation. Defaults to True. Ignored for strips.
- `finger_curl` (float, default DEFAULT_FINGER_CURL): Blend of the fingers between the relaxed hand of the rest pose (0) and the hand of the animation (1). Defaults to 1.0.
- `as_strip` (bool, default False): Add as NLA strip instead of as active action. Defaults to False.
- `frame_start` (Optional[int], default None): Scene frame of the first key. Defaults to the start frame of the scene, for strips to the end of the last Human Generator strip.

Returns: Optional[bpy.types.Action] — Optional[bpy.types.Action]: The created action, None if preset is "none".

Raises: HumGenException — If the human has a Rigify rig.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L123

### import_mixamo()

```python
human.animation.import_mixamo(filepath: str, name: Optional[str] = None, category: str = 'Mixamo', loop: bool = False, context: C = None, render_thumbnail: bool = True, finger_curl: float = DEFAULT_FINGER_CURL) -> str
```

Converts a Mixamo FBX file to a clip in the library and applies it.

The clip is saved as json in the animations folder of the content folder,
so it shows up in the animation library and can be used on other humans
too. See mixamo.py for the conversion.

Parameters:
- `filepath` (str): Path of the FBX file downloaded from Mixamo.
- `name` (Optional[str], default None): Name of the animation in the library. Defaults to the name of the file.
- `category` (str, default 'Mixamo'): Folder of the animation library to save the clip in, created if it does not exist. Defaults to "Mixamo".
- `loop` (bool, default False): Mark the animation as cyclic. Defaults to False.
- `context` (C, default None): Context to use. Defaults to None.
- `render_thumbnail` (bool, default True): Render a thumbnail of this human in the animation next to the clip. Defaults to True.
- `finger_curl` (float, default DEFAULT_FINGER_CURL): See `set`. Defaults to 1.0.

Returns: str — Preset path of the new animation, relative to the content folder.

Raises: HumGenException — If the file is not a Mixamo animation or the human has a Rigify rig.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L209

### refresh()

```python
human.animation.refresh(context: C = None, finger_curl: Optional[float] = None)
```

Retargets the Human Generator animations again, after the rig changed.

Needed after changes to the height, proportions or rest pose of the human.
The actions are updated in place, see the class docstring, and keep their
timing: the frame they start on and their length.

Parameters:
- `context` (C, default None): Context to use. Defaults to None.
- `finger_curl` (Optional[float], default None): New finger curl factor for the active animation, see `set`. Defaults to the factor it has. Animations in NLA strips keep their own factor.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L278

### push_down()

```python
human.animation.push_down() -> Optional[bpy.types.NlaStrip]
```

Moves the active Human Generator animation to a strip in the NLA editor.

Like the push down button of Blender. The action keeps its frame range and
is no longer the active action, so another animation can be set or added on
top of it.

Returns: Optional[bpy.types.NlaStrip] — Optional[bpy.types.NlaStrip]: The new strip, None if the human has no active Human Generator animation.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L344

### remove()

```python
human.animation.remove(active: bool = True, strips: bool = False)
```

Removes Human Generator animations from this human.

The animated bones return to their rest position. Actions are deleted
unless they are still used, by an NLA strip or a fake user.

Parameters:
- `active` (bool, default True): Remove the active animation. Defaults to True.
- `strips` (bool, default False): Remove the Human Generator animations in NLA strips and the tracks that become empty. Defaults to False.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L399

### set_scene_frame_range()

```python
human.animation.set_scene_frame_range(context: C = None)
```

Sets the frame range of the scene to the Human Generator animation.

One cycle of the active animation, or the range of all Human Generator
strips if there is no active animation.

Parameters:
- `context` (C, default None): Context to use. Defaults to None.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L472

### as_dict()

```python
human.animation.as_dict() -> dict[str, Any]
```

Animation settings as dict.

Returns: dict[str, Any] — dict[str, Any]: Animation settings as dict.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/animation/animation.py#L497

### set_random()

```python
human.animation.set_random(context: C = None, update_ui: bool = False)
```

*inherited from PreviewCollectionContent*

Set this content type to a random content item.

This will use random.choice to select a random item from the output of
get_options().

Parameters:
- `context` (C, default None): Blender context. bpy.context if not provided.
- `update_ui` (bool, default False): Will also show the chosen item as the active thumbnail in the template_icon_view. Defaults to False.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/common_baseclasses/pcoll_content.py#L68

### get_options()

```python
human.animation.get_options(context: C = None, category: str = 'All') -> List[str]
```

*inherited from PreviewCollectionContent*

Get a list of options you can use for the set() method of this content.

These represent the choises the user sees in the UI. The output is a list of
relative paths to the content files, starting from the Human Generator folder.

Parameters:
- `context` (C, default None): Blender context. bpy.context if not provided.
- `category` (str, default 'All'): Category to filter the content by. Defaults to "All". You can get a list of categories from the get_categories() method.

Returns: List[str] — List[str]: List of relative paths to content files. You can pick one of these and pass it to the set() method.

Raises: ValueError — If the passed category is not present in the list of categories.

Raises: HumGenException — If no options can be found, this can be caused by the content pack for this type of content not being installed.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/common_baseclasses/pcoll_content.py#L98

### get_categories()

```python
human.animation.get_categories() -> list[str]
```

*inherited from PreviewCollectionContent*

Get a list of categoris this content type is organized in.

You can choose one of these categories to filter the content retreived from
get_options().

Returns: list[str] — list[str]: List of categories. These are the names of the folders the content is saved in.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/common_baseclasses/pcoll_content.py#L148

### refresh_pcoll()

```python
human.animation.refresh_pcoll(context: C = None, override_category: Optional[str] = None, ignore_searchterm: bool = False)
```

*inherited from PreviewCollectionContent*

Refresh the items of this preview collection.

This is low level functionality, you should not need to use this. It is used
to refresh the list of possible content for this human. If you use get_options()
this is automatically done for you.

Parameters:
- `context` (C, default None): Blender context. bpy.context if not provided.
- `override_category` (Optional[str], default None): Override the category to use, if not provided all items regardless of category will be shown.
- `ignore_searchterm` (bool, default False): If True, the searchterm set by the user will be ignored. Defaults to False.

Source: https://github.com/OliverJPost/HumGen3D/blob/main/human/common_baseclasses/pcoll_content.py#L180