mikumotion

Name	mikumotion JSON
Version	2025.7.25 JSON
	download
home_page	None
Summary	None
upload_time	2025-07-30 07:25:40
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	None
keywords	motion mmd blender
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

# MikuMotionTools

MikuMotionTools contains various functions for converting MMD (MikuMikuDance) motions and other motion file formats into armature motion format that can be used in the Isaac Lab RL training environment.

## Getting Started

### Create the environment

```bash
uv sync
```

To run the examples, do

```bash
uv pip install -e .
```

### Install the library

From pip (coming soon)

```bash
uv pip install mikumotion
```

From source
```bash
git clone https://github.com/T-K-233/MikuMotionTools.git
cd ./MikuMotionTools/
uv pip install -e .
```

## Directory Structure

`blender-projects/` stores the blender project files.

`mikumotion/` stores the Python source file of the library.

`data/motions/` stores the converted motions.

`data/robots/` stores the robot asset file used during inverse kinematic solving.

Note: Due to licensing issue, the Blender project files and MMD motions should be retrieved from the original authors. For internal developers, the mirror of this directory is stored at [Google Drive]().

## Motion Format

This library uses the motion file format defined in IsaacLab [MotionLoader](https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/humanoid_amp/motions/motion_loader.py#L12).

Each motion file is a numpy dictionary with the following fields. Here, we assume the robot has `D` number of joints and `B` number of linkages, and the motion file has `F` frames.

- `fps`: an int64 number representing the frame rate of the motion data.
- `dof_names`: a list of length `D` containing the names of each joint.
- `body_names`: a list of length `B` containing the names of each link.
- `dof_positions`: a numpy array of shape `(F, D)` containing the rotational positions of the joints in `rad`.
- `dof_velocities`: a numpy array of shape `(F, D)` containing the rotational (angular) velocities of the joints in `rad/s`.
- `body_positions`: a numpy array of shape `(F, B, 3)` containing the locations of each body in **world frame**, in `m`.
- `body_rotations`: a numpy array of shape `(F, B, 4)` containing the rotations of each body in **world frame**, in quaternion `(qw, qx, qy, qz)`.
- `body_linear_velocities`: a numpy array of shape `(F, B, 3)` containing the linear velocities of each body in **world frame**, in `m/s`.
- `body_angular_velocities`: a numpy array of shape `(F, B, 3)` containing the rotational (angular) velocities of each body in **world frame**, in `rad/s`.

The converted motion file is targeted for one particular robot skeleton structure.

To ensure best performance, also make sure that the frame rate matches the training environment policy update rate to avoid expensive interpolations.

## Working with MMD

To import and convert MMD motions in Blender, the [MMD Tools](https://extensions.blender.org/add-ons/mmd-tools/) plugin needs to be installed to Blender.

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mikumotion",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "motion, mmd, blender",
    "author": null,
    "author_email": "\"-T.K.-\" <tk233.xyz@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/09/8c/47519cfc9b833ebe851cdf2329d69ac98a73f7d6dde90befbda105c225e1/mikumotion-2025.7.25.tar.gz",
    "platform": null,
    "description": "# MikuMotionTools\r\n\r\nMikuMotionTools contains various functions for converting MMD (MikuMikuDance) motions and other motion file formats into armature motion format that can be used in the Isaac Lab RL training environment.\r\n\r\n\r\n## Getting Started\r\n\r\n### Create the environment\r\n\r\n```bash\r\nuv sync\r\n```\r\n\r\nTo run the examples, do\r\n\r\n```bash\r\nuv pip install -e .\r\n```\r\n\r\n### Install the library\r\n\r\nFrom pip (coming soon)\r\n\r\n```bash\r\nuv pip install mikumotion\r\n```\r\n\r\nFrom source\r\n```bash\r\ngit clone https://github.com/T-K-233/MikuMotionTools.git\r\ncd ./MikuMotionTools/\r\nuv pip install -e .\r\n```\r\n\r\n\r\n## Directory Structure\r\n\r\n`blender-projects/` stores the blender project files. \r\n\r\n`mikumotion/` stores the Python source file of the library.\r\n\r\n`data/motions/` stores the converted motions.\r\n\r\n`data/robots/` stores the robot asset file used during inverse kinematic solving.\r\n\r\nNote: Due to licensing issue, the Blender project files and MMD motions should be retrieved from the original authors. For internal developers, the mirror of this directory is stored at [Google Drive]().\r\n\r\n\r\n## Motion Format\r\n\r\nThis library uses the motion file format defined in IsaacLab [MotionLoader](https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/humanoid_amp/motions/motion_loader.py#L12).\r\n\r\nEach motion file is a numpy dictionary with the following fields. Here, we assume the robot has `D` number of joints and `B` number of linkages, and the motion file has `F` frames.\r\n\r\n- `fps`: an int64 number representing the frame rate of the motion data.\r\n- `dof_names`: a list of length `D` containing the names of each joint.\r\n- `body_names`: a list of length `B` containing the names of each link.\r\n- `dof_positions`: a numpy array of shape `(F, D)` containing the rotational positions of the joints in `rad`.\r\n- `dof_velocities`: a numpy array of shape `(F, D)` containing the rotational (angular) velocities of the joints in `rad/s`.\r\n- `body_positions`: a numpy array of shape `(F, B, 3)` containing the locations of each body in **world frame**, in `m`.\r\n- `body_rotations`: a numpy array of shape `(F, B, 4)` containing the rotations of each body in **world frame**, in quaternion `(qw, qx, qy, qz)`.\r\n- `body_linear_velocities`: a numpy array of shape `(F, B, 3)` containing the linear velocities of each body in **world frame**, in `m/s`.\r\n- `body_angular_velocities`: a numpy array of shape `(F, B, 3)` containing the rotational (angular) velocities of each body in **world frame**, in `rad/s`.\r\n\r\nThe converted motion file is targeted for one particular robot skeleton structure. \r\n\r\nTo ensure best performance, also make sure that the frame rate matches the training environment policy update rate to avoid expensive interpolations.\r\n\r\n\r\n## Working with MMD\r\n\r\nTo import and convert MMD motions in Blender, the [MMD Tools](https://extensions.blender.org/add-ons/mmd-tools/) plugin needs to be installed to Blender.\r\n",
    "bugtrack_url": null,
    "license": null,
    "summary": null,
    "version": "2025.7.25",
    "project_urls": {
        "Source": "https://github.com/T-K-233/MikuMotionTools",
        "Tracker": "https://github.com/T-K-233/MikuMotionTools/issues"
    },
    "split_keywords": [
        "motion",
        " mmd",
        " blender"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "6d41ed291c8b5a42bdb7eebc2ba2ff0a65cab2339ba635942cbcba7c1de8586e",
                "md5": "2ba5b2e2bd3785f01526011490082dfe",
                "sha256": "b24a310b945a2055c6b827998b9da9b049c600f2f1b707038ca80e8514bf9f83"
            },
            "downloads": -1,
            "filename": "mikumotion-2025.7.25-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2ba5b2e2bd3785f01526011490082dfe",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 12945,
            "upload_time": "2025-07-30T07:25:38",
            "upload_time_iso_8601": "2025-07-30T07:25:38.932757Z",
            "url": "https://files.pythonhosted.org/packages/6d/41/ed291c8b5a42bdb7eebc2ba2ff0a65cab2339ba635942cbcba7c1de8586e/mikumotion-2025.7.25-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "098c47519cfc9b833ebe851cdf2329d69ac98a73f7d6dde90befbda105c225e1",
                "md5": "78482484e41262b330c6a348e269cce6",
                "sha256": "77edfff2b5019fe8e49d01d8ddefffd8caae541cd5756584ee38a77507c93046"
            },
            "downloads": -1,
            "filename": "mikumotion-2025.7.25.tar.gz",
            "has_sig": false,
            "md5_digest": "78482484e41262b330c6a348e269cce6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 13248,
            "upload_time": "2025-07-30T07:25:40",
            "upload_time_iso_8601": "2025-07-30T07:25:40.290430Z",
            "url": "https://files.pythonhosted.org/packages/09/8c/47519cfc9b833ebe851cdf2329d69ac98a73f7d6dde90befbda105c225e1/mikumotion-2025.7.25.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-30 07:25:40",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "T-K-233",
    "github_project": "MikuMotionTools",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "mikumotion"
}

None