Sakura Poselib

A Simpler, Lighter, and Handy Pose Library for Character Creators.

Blender Extensions GitHub

Gumroad BlenderMarket Store sites are for donation

Distributed under licence GPL-3.0

---

About

Sakura Poselib is an addon for Blender. It was created to replace the old pose library, which was gradually phased out in the Blender 3 series. With this addon, you can easily create, manage, apply poses, and use them in your animation timeline just like as Shape Keys.

This addon designed to be compatible with mmd_tools and PMX Editor. It can also import and export from old pose library.

Note

After installing the addon, Sakura Poselib panel will be added on Armature Properites Panel.
Also, Sakura tab will be added on the side panel, and you can use various features from the side panel.

Basic Features

PoseBook

PoseBook is a collection of poses in Sakura Poselib. An armature can store multiple PoseBooks. This is similar to former pose library's 'action'.

Different from action, PoseBook is not a collection of keyframes. PoseBook stores poses as colleciton of { pose_name: bone_data } structure.

Please create the first PoseBook by pressing + button when you start using Sakura Poselib.

Pose

Pose is a data that represents the state of the bones of the armature. In Sakura Poselib, the pose list is stored as a collection within the PoseBook.

A Pose in Sakura Poselib is just a simple pair of { pose_name: bone_transforms }. The bone_transforms contains list of {bone_name: transform} data, and it can be edited in 'Bone Data' subpanel within Sakura Poselib panel.

Pose Category

Poses are categorized by the identifier contained in the name, and can be displayed in different tabs of the pose list. By default, the following categories are available.

Category	Description	Identifier
ALL	All Poses	*
EYE	Poses for eyes, eyelids	eye, eyelid,目, 瞼 etc
EYEBROW	Poses for eyebrows	eyebrow, 眉 etc
MOUTH	Poses for mouth or lips	mouth, lip, 口, 唇 etc
OTHERS	Other poses	上記以外

Bone Data

Within the 'Bone Data' subpanel of the Sakura Poselib panel, you can check and edit the state of the bones included in the pose.

Info

It is difficult to directly edit the numerical values of the transform data in the bone data panel. This panel is used for checking the status, and when adjustment is required, operate the bone in pose mode and overwrite the pose data with the Replace function.

How To Use

Adding a Pose

As same as former pose library, Shift+L shows Add/Replace menu in pose mode.
When adding a pose, bones that actually contributes current pose are automatically added to pose data. You don't need to select bones to add them.

Tip

During this process, invisible bones are ignored, so you can keep pose data clean by hiding unnecessary bones in advance.

Replacing a Pose

Same as adding a pose, only bones that actually contributes current pose are automatically added to pose data. You don't need to select bones to add them. Bones that do not contribute to the pose are removed from the target pose data.

Preview Poses / Combined Pose

In the pose list, each pose has a slider, and by adjusting the value of each slider, you can preview the pose state according to the degree of application, just like a shape key.

You can also preview poses that combine multiple poses by using multiple sliders at the same time.

Alternatively, you can also create a new pose by combining multiple poses by adding a pose while previewing.

Note

This feature is currently not compatible with blender animation system. Designed for just preview purpose.

Tip

Poses from Sakura Poselib does not constrain your Armature. You can freely control boens while Pose values are active.

Animation Compatible Mode

Click the Enable Animation button under the PoseBook list to switch to Animation Compatible Mode. In this mode, the value of each pose can be keyframed, allowing you to freely use poses or combinations of poses in your animations.

For existing bone animations on the timeline, the influence of each pose is added as if it were a keyframe. This allows you to add facial animations from the pose library to existing full-body animations or vice versa.

While in Animation Compatible Mode, poses cannot be edited.

Tip

While in Animation Mode, if you change the bone configuration of the armature, you may need to toggle the Animation Mode to make it work correctly.

Note

Internally, each bone of the target armature is constrained to the pose posture by an Action constraint, and the influence is controlled by the pose value. This allows you to create animations of composite poses. Therefore, at the beginning of the mode, an action is created for each pose. When the mode is exited, these actions are deleted. If there are a large number of poses, the creation of actions may fail.

Using "Alt Names" for Poses

By enabling the "Show Alt Names" button next to the title of the pose list, the "Alt Name (alt_name)" is displayed next to the name of each pose.

This is an item for translation purposes and can be used when exporting. For example, when creating poses for MMD, you can use English names in Blender and Japanese names in MMD.

Import/Export

Sakura Poselib has several import/export features.

To access these features, click the down curret next to the PoseBook List and select 'Convert' submenu.

Pose Library (former)

Blender supports old type pose library up to 3.4. Sakura Poselib can use their data by importing from current pose library assigned on the armature.

PoseBook can also export to old pose library, but this feature is not recommended because pose library is absolutely deplecated from Blender 3.5 (Replaced with Pose Assets type pose library).

Tip

If you need to import multiple data from the old pose library, we recommend using Blender 3.12 or earlier. After Blender 3.12, you can no longer access part of the pose library function.

mmd_tools

Sakura Poselib can use MMD models bone morph data as Pose Library by importing from a MMD model that is created by mmd_tools.
You can also export your PoseBook to MMD model as Bone Morophs by using export feature in Sakura Poselib.

Info

mmd_tools is a defacto standard addon for MMD models in Blender.

File (JSON and CSV)

You can export active PoseBook to a file or import a PoseBook from a file.

• JSON:

  Only use for export/import between models witch uses Sakura Poselib.
  You can use this feature to share PoseBook data between models.
  Enabling `Use Armature Space` allows you to use the pose data while ignoring bone-rolls on each armature (True by default).
  

• CSV:

  Compatible PMX Editor (MMD model editor). You can export PoseBook to csv and use it in PMX Editor.
  Alternatively you can import CSV (Bone Morph) file which is exported from PMX Editor for Sakura Poselib's PoseBook.
  Also you can use 'Use alt Names' option to export each poses using alt names as primary key.

Tip

You can specify the scale value when exporting to CSV. This value will used for converting bone transforms to MMD's unit. (Default: 12.5)

Utility Features

Sakura Poselib has several utility features to improve usability.

Pose Preview mode (Modal)

In pose mode, you can invoke Sakura Poselib's pose preview mode by pressing Alt+L. You can switch poses and posebooks by pressing keys (see the operation description displayed in the 3D viewport for details).

This feature is not available while in Animation Compatible Mode.

Pose Data Cleaner (Operator)

Within the Sakura Poselib panel, there are some handy operator buttons.
Pose Data Cleaner button calls operator that removes unnecessary / invalid bone transforms from poses within active PoseBook.
If your pose data become invalid by renaming bones, be careful to use this (Transforms with invalid bone names will be removed!).

Bone Renaming Tool (Operator)

This is a tool to rename bones in pose data. It is useful when you want to retarget PoseBooks to another model.
In addition to normal string search and replace, regular expressions can be used.

Bone Name Tracker (Background Handler)

This is a background handler type feature. It will work automatically when the addon is enabled.
When the bone name is changed, the bone name in the pose data is automatically synchronized, so you can edit the armature without worrying about breaking the pose data.

Technical Notes

• Sakura Tools addon for Blender has a feature to convert Sakura Poselib's PoseBook data to shape keys.

• Sakura Poselib's data can be used for any purposes.

• Sakura Poselib's Data Layout: (see props.py for more details)

• bpy.types.Object.sakura_poselib

  • Books: Colleciton of PoseBook
  • name: PoseBook name
  • Poses: Colleciton of Pose
    • Pose: { pose_name: List[BoneTransform] }
    • name: Pose name
    • Bones: Colleciton of BoneTransform
      • BoneTransform: { bone_name: location:Vector3, rotation:Quaternion, scale:Vector3 }

• See the source code for more details.

---