# MotionWeaver: Beginner's Motion Injection Guide (v9)
~ Manual for 3D Motion Spatial Analysis and 2.5D Conversion ~

Last Updated: 2026/04/21

This guide will walk you through the procedures for mastering "MotionWeaver," the core of the Weaver series, to deliver 3D performances to your characters. This guide is a handbook for minimizing complex settings and mastering the workflow for synchronizing your drawings with 3D data.

---

## 0. MotionWeaver Concept: "Translating" 3D into 2.5D Puppet Values

### A "Data Translator" for 2.5D Animation Production
MotionWeaver functions as a "translator" that converts 3D movement (BVH data) into a numerical format (CSV) that is easy to handle in 2.5D animation environments (such as Moho). By organizing complex 3D rotation data into "angles" and "coordinates (including Z-depth)" that Moho rigs can interpret, it generates high-quality "performance data" that serves as the foundation for rigging work.

---

### 🌟 4 Key Points of Motion Injection

#### 1. "Translate" 3D Bone Names into 2D Names
**Instantly convert the skeleton of a 3D character to match the specifications of a 2D puppet.**
It automatically links bone names of 3D data (e.g., `LeftUpLeg`) to bone names of your 2D character (e.g., `LThigh`). This prepares you to smoothly "inject" 3D motions of different standards into your illustrations.

#### 2. "Performance Dress-up" Completed with a Single Button
**Once the setup is created, subsequent motion application is instant.**
Create a setting (profile) for each character once, and from then on, simply selecting another BVH file will generate new performance data one after another. You can immediately verify and export multiple dances or actions for the same character.

#### 3. Creating a Solid Foundation for "Lying in 2D"
**Provides material for "messing around" with 3D logic through 2D expression.**
MotionWeaver is intentionally designed to leave "visual adjustments" to the Moho side (RigWeaver). By loading the CSV exported by MotionWeaver into Moho, you get a solid "foundation" for adding "flair unique to 2D," such as swapping the overlapping order of layers or exaggerating perspective.

#### 4. Turning All 3D Assets into an Animation "Hub"
**Make the most of the 3D data you have.**
Your own movements captured with smartphone apps (such as TDPT), Mixamo data, performances in your favorite Poser—MotionWeaver accepts all of these and converts them into "direction CSVs" that are easiest to handle in Moho.

---

### 🛠️ Main Tasks of MotionWeaver: 3 Major Functions

- **A. Retargeting**: 
  "Translates and transfers" 3D joint information into names and structures for Moho rigs.
- **B. Cleaning (Spike Suppression)**: 
  Detects unnatural vibrations or noise unique to 3D capture and corrects them smoothly so that jittering is not noticeable in 2D.
- **C. Exporting (Ejecting Direction Data)**: 
  High-speed generation of instruction sheets in `_3d.csv` format that Moho (RigWeaver) can load as "performance drafts."

---

## Chapter 1: Preparation Before Starting Work (Procuring Materials)

MotionWeaver is a "motion injection machine" for reproducing 3D performances into 2.5D values. To succeed in this process, you need to have the following three elements ready in advance.

1. **"Source Performance": Source BVH (3D Motion Data)**
   - The record of the "performance" itself you want to move (.bvh), created with Mixamo, TDPT, etc.
2. **"Injection Target Template": Target BVH (Character Skeleton)**
   - A BVH that serves as a "template" defining the skeletal structure of the final output destination (Moho, Poser, etc.). Data for at least one frame is sufficient.
3. **"Injection Dictionary": Profile (Correspondence Table)**
   - A definition file (.json) of rules for "which source bone to connect to which target bone." **This dictionary (setting) is something you create and save yourself during the first task**, and once created, "instant injection" becomes possible from the next time.

### 1.1 Premise: Where to get motions (BVH)?
BVH can be obtained or created very easily. Please prepare them using any of the following methods:
- **Download from free asset sites**: Get your favorite movements from Adobe's "Mixamo" and others.
- **Create by "moving yourself" using a smartphone or AI**: Use apps like "TDPT" to film yourself with a smartphone camera and convert it to BVH.
- **Create with 3D tools (Poser, Blender)**: Unique motions you've created yourself and exported.

### 1.2 Prepare the "Template (Target)" for Conversion
This is the **"taiyaki mold"** that determines "which software's skeleton to ultimately output this movement to match."

**MotionWeaver is not "only for Moho."** Simply by changing the "template (target)" you load, you can export movement to any platform.
- **When making animation with Moho**: Load `moho_Template.bvh` as the template.
- **When exporting to Poser, etc. (your own template)**: Simply exporting a 1-frame BVH of a standing character from the 3D software you own will result in your own unique "template."
- **[Success Story] Making Poser's "mini" character dance**: By using `mini.bvh`, a 1-frame export of the mini skeleton, as the template, a workflow has been proven where your dance is instantly injected into the mini in Poser space to make it dance.

---

## Chapter 2: Handling the Start Frame (Mode 1 and Mode 2)

We will explain extremely important principles that affect the animation work efficiency of creators.

### 2.1 Major Principle: Choose "Mode 1 (Standard)" as the Base
Normally, illustrations are drawn in natural "A-poses," etc. **"Mode 1 (Standard)"** is a function that **"constructs bones at natural angles according to the pose of the illustration you drew."** Since it is set up exactly in the posture at the time of drawing, subsequent performance-giving on Moho becomes overwhelmingly intuitive.

### 2.2 "Mode 2 (Insert Base Pose)" as a Rescue

Mode 2 is an **"emergency rescue measure when the pose of the drawing was too extreme, and the moment 3D motion was injected, the character's joints twisted or the mesh collapsed (became a monster)."**

When you switch to Mode 2 (Insert Base Pose), the pose of the illustration is temporarily ignored forcibly, and **"at frame 0, the original frame 1 (base pose) of the BVH data is forcibly inserted and restored."**

For humanoid models, this base pose is often a "mathematically straight T-pose." By re-measuring the length of the limbs based on this, it becomes possible to force through and avoid mesh collapse even under the most severe conditions. Even for characters that don't have T-poses, such as quadruped models, stable rigging is achieved by restoring the "neutral origin" for that model.

---

## Chapter 3: Practical Workflow (Single Conversion)

### Step 1. Data Setup (Specifying Files)
1.  Launch MotionWeaver.
2.  Specify the necessary files in the **"1. File Selection"** area.
    - **Source BVH**: Select the raw motion data (.bvh) using the "Browse..." button.
    - **Target / Profile**: Select the prepared "template" or a saved profile.
    - **PSD Static Rig Generation ONLY (Optional)**: Specify the PSD file here only when creating a PSD rig via batch execution from LayerWeaver, etc. Leave blank for standard BVH conversion.
3.  Loading is completed in an instant, and lists of the source (left) and target (right) are lined up in the mapping area on the left side of the screen.

### Step 2. Bone Injection Settings (Mapping) in Practice
1.  Open the **"Center"** tab, select the bone corresponding to "Hip" (e.g., `mixamorig:Hips`) from the left side, select `Hip` from the right side, and press **"< Assign."**
2.  Repeat this to connect the spine, neck, and head. Similarly, map the left and right arms and legs in the "Left" and "Right" tabs.
- **[Operation Hint] What to do with extra fingertip bones?**: If the target does not have bones that are too detailed, such as the first joint of a finger, the recommended setting is to press the **"< Neutralize (All)"** button after selecting them on the left side to maintain them as "non-moving bones."
- **⚠Warning (Caution for None Delete)**: If you delete the bone itself with the **"< Delete Bone (None)"** button, the CSV column will disappear, causing an error in subsequent RigWeaver where "necessary data cannot be found." Unless there is a special reason, maintain mapping or respond with "Neutralize."

### Step 3. Determining Viewpoint and Motion Settings
1.  Determine details with the **"Adjust Viewpoint..."** and **"Motion Settings..."** buttons.
    - **Target Mode**: Select `3D Full (Standard)`.
    - **Start Frame Processing**: Basically **`Mode 1 (Standard)`**.
2.  Confirm with **"Apply."**

### Step 4. Saving the Profile and Responsiveness
1.  Save this injection rule with a name using **"Save Profile..."**
2.  This profile is a powerful asset. Even if there are changes to the 3D action tomorrow, simply loading the profile and pressing **"Run Conversion"** will re-export the latest `_3d.csv` in a few seconds.

> **[Final Test]**: Before going to Moho, press **"Play"** in the **"3D Viewer"** on the right side of the screen. We recommend dragging the border (splitter) to enlarge the viewer and check carefully to ensure the bones move without twisting.

---

## Chapter 4: Professional Practical Workflow (Mass Production by Batch Processing)

Placing special markers (FW, RW, etc.) on the Moho timeline, or placing multi-actions (`path|start` markers) on the timeline to issue a bake instruction, generates **`RUN.bat`** in the folder. This is an **"instruction sheet for batch processing or motion injection for MotionWeaver."**

You no longer need to operate the screen individually. **Just run `RUN.bat`.** MotionWeaver starts in the background and automatically scans, generates, or updates the CSV data (2.5D spatial coordinate data containing Z-depth) required for specified angles or multiple actions. The generated data will be automatically batch-bound and baked on RigWeaver.

---

## Chapter 5: Practical Troubleshooting Collection

### 5.1 It says "Target name is being stolen!"
This is a warning that another bone is already using the name on the right side. In most cases, you are trying to link the same bone or reversed left/right bones twice. Press "No" and review the contents in the tabs.

### 5.2 Arms are unnaturally buried in the body!
Make full use of the 2D animator's privilege. By **swapping the Z-order (depth) on the Moho side or lying about perspective (deformation) with vector deformation** only for the moment they are buried, you can correct it perfectly in seconds. Correcting on a 2D canvas is much more powerful and easier than fighting mesh collapse in 3D.

---
*MotionWeaver: Beginner's Motion Injection Guide (v9) - Completed*
