Sakura Poselib¶

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

Gumroad BlenderMarket Store sites are for donation

Released under the MIT License

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, and apply poses.

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

Panel

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 Book

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 List

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	上記以外

ボーンデータ¶

Sakura Poselibパネル内の 'ボーンデータ' サブパネルでは、ポーズに含まれるボーンの状態を確認、編集できます。
Within the 'Bone Data' subpanel of the Sakura Poselib panel, you can check and edit the state of the bones included in the pose.

Bone Data

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.

Pose Menu

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.

Replace Pose

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.

Combined Pose

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.

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.

Alt Name

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.

Import/Export

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.
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.

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).

Pose Preview 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 Rename Tool

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¶

This addon is not compatible with Blender's animation system at this time.
Sakura Tools addon for Blender can handle Sakura Poselib's PoseBook data.
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.pose_library_plus
    - Books: Colleciton of PoseBook
      - name: PoseBook name
      - Poses: Colleciton of Pose
        - Pose: { pose_name: list of BoneTransform }
          - name: Pose name
          - Bones: Colleciton of BoneTransform
            - BoneTransform: { bone_name: location(Vector3), rotation(Quaternion), scale(Vector3) }

You can use Sakura Poselib's PoseBook data for any purposes.
See the source code for more details.

Feature Plans¶

PoseBook to Pose Asset converter and vice versa.
Make PoseBook compatible with Blender's animation system by using