# MotionWeaver: Professional Technical Specifications (v10.0)
~ Definition of Spatial Analysis Engine, Retargeting Logic, and Core Data Structures ~

Last Updated: 2026/04/21

This document is a comprehensive technical specification for MotionWeaver (Spatial Analysis Engine). Its purpose is to enable animators to properly convert 3D geometric data into 2D animation deformation expressions by understanding its internal logic, and to utilize various 3D assets as their own expressions.

---

## 1. Basic Principles of the Spatial Analysis Engine

MotionWeaver is a high-precision motion injection engine that performs geometric coordinate transformation of "bone rotation data (BVH)" in 3D space to fit a 2.5D animation environment (Moho).

### 1.1 Euler Angle Decomposition and Reconstruction
Dynamically decomposes and recalculates the **YXZ rotation order** commonly used in 3D software (Poser, Blender, etc.) into Moho's unique X-Y-Z coordinate system.
- **Conversion Law**: 
  When converting 3D depth (Z-coordinate) into 2.5D depth (Z-value and Z-order), physical axis swaps (such as exchanging X-axis and Z-axis) are automatically executed based on the profile.

### 1.2 Retargeting: Universal Hub
Achieves motion transfer (injection) between models with different bone hierarchies.
- **Correction by Template**: By loading a target BVH, differences in initial bone angles (rest pose) are automatically calculated, and only the deviations are extracted and applied.

### 1.3 Protection of Rotation Continuity (Ambiguity Resolution)
Resolves ambiguity (the problem where multiple numerical values exist for the same posture) that occurs in the calculation of 3D rotation data, suppressing "jumping" in animation.
- **Euler Filter**: By referring to the rotation value of the previous frame and selecting the angle with the shortest distance, smooth continuity is guaranteed without bones twisting off even during intense action.

### 1.4 Spatial Projection and Perspective Constant
Geometric constants for faithfully converting depth information in 3D space into "scale" and "coordinates" on a 2.5D canvas.
- **VIZ_ZOOM_FACTOR (3.732...)**: A unique magnification constant linking camera field of view and canvas width. This allows a 1cm movement in 3D space to be reproduced as an accurate pixel amount on the 2.5D canvas.
- **Camera Z (Perspective Intensity)**: A distance constant for converting depth in 3D space into "scale change" on a 2.5D canvas.
    - **Default Behavior**: If not explicitly specified by an argument during conversion or in CUI mode, `motion_perspective_default_z` in `templates.json` (standard value 8.0) is referenced.
    - **Engineering Role**: This value determines the "compression rate" of perspective. The smaller the value, the stronger the perspective, making magnification more prominent as the character approaches the camera. Conversely, increasing the value results in stable output with less size variation, closer to telephoto lenses or parallel projection.
    - **Adaptation to Data Sources**: Even when handling sources with intense depth movement like TDPT, appropriately setting this value allows for maintaining natural perspective without visual collapse as illustrations.

---

## 2. Core File Physical Specifications and Knowledge Accumulation (Configuration & Growth)

The versatility of Weaver lies in its "configuration-based" design that completely separates the program (logic) and data (configuration definition).

### 2.1 bvh_knowledge.json (Statistical Mapping Inference System)
Mapping (injection settings) performed by users in the past is automatically accumulated as statistical data in **`bvh_knowledge.json`**.
- **Inference Algorithm**: When an unknown BVH is loaded, the most probable injection correspondence (e.g., `Pelvis` → `Hips`) is automatically proposed from past successful cases.
- **Dictionary Optimization**: The **"Update Dictionary (Knowledge Base)"** button at the top right of the screen rescans all profiles in the current working directory to optimize inference accuracy to the latest state.

### 2.2 synonyms.json (Absorption of Notation Fluctuations)
It incorporates a "synonym dictionary" for identifying different part names across software, such as `Hips`, `Pelvis`, and `Waist`. This allows for transparent handling of BVH materials from around the world across standard barriers.

### 2.3 Search Priority of templates.json (3-tier Search)
The configuration file `templates.json` is automatically searched with the following priority (3 tiers) to protect the flexibility of the environment.
1.  **Local (Directly under PSD folder)**: By placing the configuration file in the same location as the open PSD, rules dedicated to a specific character (bone configuration, etc.) can be applied with the highest priority.
2.  **Pointer (External Pointer Specification)**: Refers to the absolute path described in `templates_path.txt`. Used when each client refers to common settings on a server in team production, etc.
3.  **System (App folder)**: Default settings in the same hierarchy as `MotionWeaver.py`. Functions as the final fallback (Base Configuration) when none of the above are found.

### 2.4 templates.json: Master Catalog and Skeleton Definition
An index of the system defining "absolute standards" for all profiles, serving as a blueprint for PSD rigging.
- **Skeleton Topology and Standard Pose**: Stipulates bone parent-child relationships such as Human_V2 (biped) and Quadruped (four-legged), and the "rest pose" that serves as the starting point for conversion. This determines the visual sense of scale in MotionWeaver and the "zero point" for deviation calculation during injection.
- **Inheritance to Auto-Rigging**: The hierarchical structure defined here is passed on as the blueprint (reference) for Moho bone construction in RigWeaver.

### 2.5 Expansion of Language Resources (Internationalization)
To support global production environments, all UI strings in the Weaver system are completely independently defined as external JSON resources.
- **Auto-scan of lang*.json**: At application startup, `lang*.json` in the execution directory are scanned collectively, and a multi-language switching menu is dynamically constructed based on the value of the `_language_name` key in the files.
- **Localization Logic**: By simply duplicating the existing `langja.json`, translating values, and saving with a different name (e.g., `langcn.json`), any language environment can be constructed without contaminating the engineering logic of the system.

---

## 3. Operation Flow and Data Management (Logical Management)

In addition to standalone intuitive UI operation, MotionWeaver features advanced data output and external linkage specifications to support automation for the entire Weaver series.

### 3.1 Argument Protocol (Automated Ordering)
MotionWeaver supports "Silent Execution" from the OS command line, and **`RUN.bat`** generated by Moho (RigWeaver) functions as an "automated order sheet" based on this protocol.

| Argument | Physical Role | Details |
| :--- | :--- | :--- |
| `-src` | Source BVH path | Specifies the source "performance" data. |
| `-tgt` | Target BVH path | Specifies the "template" that serves as the standard for output. |
| `-prof` | Profile path | Specifies the linkage (correspondence dictionary) file (.json). |
| `-out` | Output CSV path | Specifies the save destination for 2.5D spatial coordinate data (_3d.csv). |
| `-rig` | Output RIG path | Specifies the save destination for skeletal hierarchy data (_rig.csv). |
| `-view` | Viewpoint parameters | Defines camera angles (x, y, z, rx, ry, rz) during conversion. |
| `-mode` | Processing mode | Determines the logic for the start frame (1 or 2). |

### 3.2 Physical Schema and Role of Output Data (Data Specs)
After injection, the following CSV files are generated in the specified directory as "data batons."
1.  **`*_3d.csv` (Coordinate and Rotation Data)**: Stores spatial coordinates (X, Y, Z) of the character and rotation angles (rX, rY, rZ) of the Root (Hip). This is the source of "movement" and "depth" for bones in Moho.
2.  **`*_rig.csv` (Skeleton Definition Data)**: Describes "parent-child relationships (hierarchical structure)" of all bones identified from the PSD. RigWeaver refers to this file to automatically construct an accurate bone hierarchy on Moho.

### 3.3 Viewpoint Angle Control (Virtual Camera)
Spatial correction logic for extracting 3D motions at optimal angles matched to 2D illustration perspective, such as "Front, Side, Low-angle, High-angle."
- **Optimization of Spatial Projection**: By including camera rotation offset in calculations, actual movements in 3D space are dynamically converted into the "best-looking projection" on a 2.5D canvas. This is a directorial coordinate adaptation process to match joint overlap and perspective compression to the illustration's intent.

### 3.4 Automatic Suppression of Rotation Spikes (Spike Suppression)
An internal filter that physically suppresses sudden "jumping (Spikes)" of bones caused by noise unique to 3D data or ambiguity of calculation.
- **Filter Specifications**: If the amount of rotation change between frames exceeds an internal threshold, the system determines it as "physically impossible noise" and smoothly interpolates and attenuates it from preceding and following values. This ensures calm behavior characteristic of 2D/2.5D animation.

---

## 4. Logic of Advanced Diagnostics and Mode Selection (Logical Diagnostics)

### 4.1 Bone Usurping and Conflict Resolution
When attempting to assign a second source joint to a single target bone, the system issues a **"Usurping"** warning to prevent physical inconsistency beforehand.
- **Logical Background**: A protection function for mathematical consistency to prevent contradictions, such as two brains sending commands to a single muscle.

### 4.2 Logical Selection of Processing Processes (Mode 1 and Mode 2)
Logical criteria for choosing the start frame processing that determines the success or failure of animation construction.

1.  **Mode 1 (Standard Pose Synchronization / Illustration-Based)**: 
    The "illustration pose" you drew is adopted as the starting point for calculation. Since initial bone angles are maintained naturally, this mode provides the most intuitive and high-precision results in normal setup.
2.  **Mode 2 (Base Pose Extraction / Trim Safety Device)**: 
    A rescue mode essential when the illustration pose is extreme or during "Trim" operations where a part is extracted from a long BVH duration.
    - **Injection Logic**: The "original frame 1 (base pose) of the BVH" that should have been discarded by trimming is forcibly extracted and restored to frame 0 of the output data.
    - **Practical Merit**: Even if the trim start point is an intense action (crouching, raising arms, etc.), the rigging engine refers to this restored frame 0 as the "Rest Pose (origin of calculation)." This logically avoids mesh collapse (monsterization) due to pose deviation and achieves stable rigging.

### 4.3 SOS Protocol: Engineering Support
If injection fails in an unknown BVH structure, random adjustment is strictly prohibited.
- **Provided Data**: Full text of `MotionWeaver.log`. This records the mathematical calculation process and which bones had calculation abnormalities (NaN, etc.) in detail.
- **Solution**: Based on the log, most twists can be solved simply by fine-tuning `initial_angles` in the profile.

### 4.4 Exception Handling: Logic of Neutralize and None
Mapping commands on the UI are powerful logical interventions to intentionally "sever" or "fix" the physical continuity of data.

#### None (Delete) Logic
Completely purges (excludes) source joints from the calculation process and stops writing to the output data (CSV).
- **Logical Entity**: Blockage of data flow.
- **Operational Role**: Treats 3D-specific auxiliary bones that do not exist on the 2D rig side or noise sources that adversely affect rigging calculations as "non-existent." This avoids construction errors in RigWeaver and maintains data consistency.

#### Neutralize (Fix) Logic
Discards dynamic changes across all frames of the target bone and forcibly applies and locks **only the value of "Frame 0 (Frame 1 of BVH source)"**.
- **Logical Entity**: Clamping to a Static Pose.
- **3 Forms of Neutralization (Engineering Choices)**:
    1.  **Neutralize (All)**: Fixes both rotation and position with a single value. Used to suppress movement of the Root bone for performance in place, or to make specific primary bones immobile.
    2.  **Neutralize (Rotation)**: Maintains position data while fixing only rotation to the initial angle of the illustration. Effective when wanting to keep bone "orientation" constant for the convenience of the illustration.
    3.  **Neutralize (Position)**: Maintains rotation data while fixing only position. Optimal for reflecting only rotational performance in place without moving the bone's pivot position.

#### [Wisdom from the Field] Logical Sealing of Surplus Bones via "Neutralization"
When terminal bones not existing in the target rig (e.g., first joint of a finger) are included in the BVH source, the professional practice is to explicitly apply "Neutralize" rather than simply letting them pass with "Maintain Name."

- **Data Hygiene**: With "Maintain Name," intense motion data of bones not existing in the target is output to the CSV as is. Applying "Neutralize" rewrites the values of these unnecessary columns to "Stationary (value of Frame 0)," keeping CSV data in an engineered clean state.
- **Future-proofing**: When the rig is later modified to add those bones, the risk of unexpected noise or distorted poses included in the past BVH suddenly being reflected upon injecting past CSVs can be avoided.
- **Structural Stability**: Unlike "None (Delete)," the CSV column structure itself is maintained, so it is possible to safely "logically seal" only the motion without breaking the data consistency of the entire Weaver series.

---

## 5. Conclusion: Conversion Logic Supporting Flexible Expression

MotionWeaver is a conversion engine for bridging the mathematical correctness of 3D data to the logic of 2.5D animation and building an efficient production pipeline. By understanding the data mechanism and properly operating the tool, various 3D assets can be efficiently utilized to expand the range of animation production.

---

## 6. UI Integration Reference (GUI Logic Mapping)

This chapter defines how each setting item on the GUI links to internal logical sections.

### 6.1 File Operations and Knowledge Base

| UI Item | Physical Function / Role | Related Logic (Link to this Specification) |
| :--- | :--- | :--- |
| **Source BVH** | Specify the source motion data (bone rotation information). | Chapter 1: Spatial Analysis Input |
| **Target / Profile** | Specify the "template" or existing profile to apply motion to. | Section 2.4: Master Catalog |
| **PSD Static Rig Generation ONLY** | Dedicated section for extracting bone structures from PSD. Independent of BVH flow. | Section 2.4: Rigging Design |
| **Update Dictionary** | Re-scan information in the current folder and update statistics. | Section 2.1: Statistical Inference |
| **Language** | Switch `lang*.json` and replace all UI display terms. | Section 2.5: Internationalization |

### 6.2 Mapping Edit Commands

| UI Item | Physical Function / Role | Internal Logic / Processing |
| :--- | :--- | :--- |
| **< Assign** | Bind source joint to target bone. | Section 2.1: Mapping Inference |
| **< Keep Name** | Convert with the source name. Effective when BVH structures are identical. | Minimization of Retargeting |
| **< Neutralize (All/Rot/Pos)** | Discard movement and lock specific values. Used for Root fixing or extremity acting. | Section 4.4: Logic of Neutralization |
| **< None (Delete)** | Purge target bone from calculation process and block data output. | Section 4.4: Logic of Deletion |
| **L -> R Auto Input** | Auto-complete symmetry bones. Performs L/R replacement and special tags with high precision. | Enhanced Mirroring Logic |

### 6.3 Motion Settings Dialog

| UI Item | Physical Function/Role | Internal Logic/Processing |
| :--- | :--- | :--- |
| **Start Frame (Mode 1)** | Adopts start frame of motion data as is as the starting point. | Section 4.2: Standard Pose Sync |
| **Start Frame (Mode 2)** | Extracts frame 1 (base pose) and forcibly inserts it at the beginning. | Section 4.2: Trim Safety Device |
| **Spike Removal (Degree)** | Detects sudden rotation changes between frames and attenuates/interpolates. | Section 3.4: Spike Suppression |
| **Trimming (Range)** | Reconstructs only specified time axis as data starting at 0.0s. | Redefinition of space/time |

### 6.4 Viewpoint Settings and Diagnostics Panel

| UI Item | Physical Function / Role | Internal Logic / Processing |
| :--- | :--- | :--- |
| **Adjust Viewpoint...** | Apply common offset to the Root bone for all frames. | Section 3.3: Virtual Camera |
| **3D Preview** | Always displayed on the right of the 2-column layout. Real-time visualization. | Section 1.4: Spatial Projection |
| **Diagnostics (Log)** | Always displayed on the bottom right of the 2-column layout. Records integrity and history. | Chapter 4: Advanced Diagnostics |

---

## Chapter 7: Major Parameter Cross-Reference for templates.json (MotionWeaver Only)

MotionWeaver refers to the following items in `templates.json` during 3D motion analysis, scale conversion, and data export for 2.5D.

| Parameter Name | Engineering Role | Example Setting |
| :--- | :--- | :--- |
| **`hip_offset_axis`** | **Hip Vertical Axis Definition**: Coordinate axis corresponding to vertical movement of the Hip bone in BVH data. | `"Y"` or `"Z"` |
| **`mismatch_indicators`** | **Scale Error Detection**: Primary bones used for model size comparison. Issues warning if error is large. | `["Spine", "Shoulder", "Chest"]` |
| **`horizontal_parts`** | **Horizontal Structure Definition**: Defines bone hierarchies that line up horizontally, such as in quadruped characters. | `["Spine", "Neck", "Head"]` |
| **`joint_maps`** | **Bone Translation Dictionary**: Synonyms for automatically converting input 3D bone names (source) to Moho bone names (target). | `{"Pelvis": "Hip", "Spine1": "Chest"}` |
| **`motion_perspective_default_z`** | **Default Perspective Constant**: Standard perspective reference value used when Camera Z (perspective intensity) is not specified during conversion, or for previews. | `8.0` |

---
*MotionWeaver: Professional Technical Specifications - Final Integrated Reference*
