Initial commit
This commit is contained in:
Zhongwei Li
1229
skills/references/addon-api-reference.md
Normal file
1229
skills/references/addon-api-reference.md
Normal file
File diff suppressed because it is too large
Load Diff
653
skills/references/bone-mapping-guide.md
Normal file
653
skills/references/bone-mapping-guide.md
Normal file
@@ -0,0 +1,653 @@
|
||||
# Bone Mapping Guide
|
||||
|
||||
Complete guide to the automatic bone matching system for animation retargeting.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Bone Mapping Modes](#bone-mapping-modes)
|
||||
- [Auto Bone Matching Algorithm](#auto-bone-matching-algorithm)
|
||||
- [Two-Phase Workflow](#two-phase-workflow)
|
||||
- [Quality Assessment](#quality-assessment)
|
||||
- [Blender UI Panel](#blender-ui-panel)
|
||||
- [Common Mapping Patterns](#common-mapping-patterns)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Bone mapping is the process of establishing correspondence between bones in the Mixamo animation skeleton and bones in your custom character rig. Accurate bone mapping is essential for successful animation retargeting.
|
||||
|
||||
**Why Bone Mapping Matters:**
|
||||
- Mixamo uses standardized bone names (e.g., "mixamorig:Hips", "mixamorig:LeftArm")
|
||||
- Custom rigs use various naming conventions (e.g., "Hips", "LeftArm", "left_arm", "arm.L")
|
||||
- Without proper mapping, animations won't transfer correctly
|
||||
- Incorrect mapping can result in twisted limbs, inverted rotations, or broken animations
|
||||
|
||||
**Core Features:**
|
||||
- ✅ **Automatic Fuzzy Matching** - Intelligently matches bones by name similarity
|
||||
- ✅ **UI Confirmation Workflow** - Review and edit mappings in Blender before applying
|
||||
- ✅ **Quality Assessment** - Automatic evaluation of mapping quality
|
||||
- ✅ **Rigify Presets** - Built-in support for Rigify rigs
|
||||
- ✅ **Custom Mappings** - Support for non-standard rigs
|
||||
|
||||
---
|
||||
|
||||
## Bone Mapping Modes
|
||||
|
||||
Three modes are available for bone mapping:
|
||||
|
||||
### 1. Auto Mode (Recommended) ⭐
|
||||
|
||||
**When to Use:** Unknown or non-standard rigs
|
||||
|
||||
```bash
|
||||
blender-toolkit retarget --target "Hero" --file "./Walking.fbx" --mapping auto
|
||||
```
|
||||
|
||||
**How It Works:**
|
||||
1. Analyzes both source (Mixamo) and target (your character) bone names
|
||||
2. Uses fuzzy matching algorithm to find best matches
|
||||
3. Generates mapping with similarity scores
|
||||
4. Displays mapping in Blender UI for user review
|
||||
5. User confirms or edits before application
|
||||
|
||||
**Advantages:**
|
||||
- Works with any rig structure
|
||||
- No manual configuration required
|
||||
- Intelligent name matching handles various conventions
|
||||
- User confirmation ensures accuracy
|
||||
|
||||
**Similarity Algorithm:**
|
||||
- Base matching using SequenceMatcher
|
||||
- Bonuses for substring matches
|
||||
- Bonuses for common prefixes (left, right, upper, lower)
|
||||
- Bonuses for common suffixes (.L, .R, _l, _r)
|
||||
- Bonuses for number matching (Spine1, Spine2)
|
||||
- Bonuses for anatomical keywords (arm, leg, hand, foot)
|
||||
|
||||
### 2. Rigify Mode
|
||||
|
||||
**When to Use:** Standard Rigify rigs
|
||||
|
||||
```bash
|
||||
blender-toolkit retarget --target "Hero" --file "./Walking.fbx" --mapping mixamo_to_rigify
|
||||
```
|
||||
|
||||
**How It Works:**
|
||||
- Uses predefined Mixamo → Rigify bone mapping
|
||||
- Optimized for standard Rigify control rig structure
|
||||
- Instant mapping with high confidence
|
||||
|
||||
**Advantages:**
|
||||
- Zero configuration for Rigify users
|
||||
- Highest accuracy for Rigify rigs
|
||||
- Immediate application (no UI review needed)
|
||||
|
||||
**Rigify Bone Naming:**
|
||||
```
|
||||
Mixamo Rigify
|
||||
-------- ------
|
||||
Hips hips
|
||||
Spine spine_fk
|
||||
Spine1 spine_fk.001
|
||||
Spine2 spine_fk.002
|
||||
Neck neck
|
||||
Head head
|
||||
LeftShoulder shoulder.L
|
||||
LeftArm upper_arm_fk.L
|
||||
LeftForeArm forearm_fk.L
|
||||
LeftHand hand_fk.L
|
||||
```
|
||||
|
||||
### 3. Custom Mode
|
||||
|
||||
**When to Use:** Unique rig structures with known mappings
|
||||
|
||||
```typescript
|
||||
// In your workflow code
|
||||
const customMapping = {
|
||||
"Hips": "Root",
|
||||
"Spine": "Torso_01",
|
||||
"Spine1": "Torso_02",
|
||||
"LeftArm": "L_UpperArm",
|
||||
"RightArm": "R_UpperArm"
|
||||
};
|
||||
|
||||
await workflow.run({
|
||||
targetCharacterArmature: 'MyCharacter',
|
||||
animationFilePath: './Walking.fbx',
|
||||
boneMapping: customMapping
|
||||
});
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Full control over mapping
|
||||
- Reusable across multiple animations
|
||||
- No UI confirmation needed if mapping is trusted
|
||||
|
||||
---
|
||||
|
||||
## Auto Bone Matching Algorithm
|
||||
|
||||
The fuzzy matching algorithm intelligently pairs bones from Mixamo skeleton to your character rig.
|
||||
|
||||
### Phase 1: Normalization
|
||||
|
||||
All bone names are normalized before comparison:
|
||||
|
||||
```python
|
||||
# Input variations
|
||||
"Left_Arm" → "left_arm"
|
||||
"left-arm" → "left_arm"
|
||||
"LeftArm" → "leftarm"
|
||||
"Left Arm" → "left_arm"
|
||||
"left.arm" → "left_arm"
|
||||
```
|
||||
|
||||
**Normalization Steps:**
|
||||
1. Convert to lowercase
|
||||
2. Replace special characters with underscore
|
||||
3. Remove consecutive underscores
|
||||
4. Strip leading/trailing underscores
|
||||
|
||||
### Phase 2: Similarity Calculation
|
||||
|
||||
Calculates similarity score (0.0 - 1.0) between bone names:
|
||||
|
||||
```python
|
||||
def calculate_similarity(name1: str, name2: str) -> float:
|
||||
# Base score from SequenceMatcher
|
||||
base_score = SequenceMatcher(None, norm1, norm2).ratio()
|
||||
|
||||
# Bonus factors
|
||||
bonus = 0.0
|
||||
|
||||
# Substring match: +0.15
|
||||
if norm1 in norm2 or norm2 in norm1:
|
||||
bonus += 0.15
|
||||
|
||||
# Prefix match (left, right, etc): +0.1
|
||||
# Suffix match (.L, .R, etc): +0.1
|
||||
# Number match (Spine1, Spine2): +0.1
|
||||
# Keyword match (arm, leg, etc): +0.05
|
||||
|
||||
return min(base_score + bonus, 1.0)
|
||||
```
|
||||
|
||||
**Example Scores:**
|
||||
```
|
||||
"LeftArm" ↔ "left_arm" = 0.95 (substring + prefix)
|
||||
"LeftArm" ↔ "L_Arm" = 0.78 (keyword + suffix)
|
||||
"LeftArm" ↔ "RightArm" = 0.65 (keyword only)
|
||||
"LeftArm" ↔ "LeftLeg" = 0.42 (prefix only)
|
||||
"LeftArm" ↔ "Head" = 0.15 (no match)
|
||||
```
|
||||
|
||||
### Phase 3: Best Match Selection
|
||||
|
||||
Selects the best match for each source bone:
|
||||
|
||||
```python
|
||||
def find_best_match(source_bone, target_bones, threshold=0.6):
|
||||
best_match = None
|
||||
best_score = 0.0
|
||||
|
||||
for target_bone in target_bones:
|
||||
score = calculate_similarity(source_bone, target_bone)
|
||||
|
||||
if score > best_score and score >= threshold:
|
||||
best_score = score
|
||||
best_match = target_bone
|
||||
|
||||
return best_match
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Only matches above threshold (default: 0.6) are considered
|
||||
- Each target bone can only be matched once (prevents double mapping)
|
||||
- Returns `None` if no suitable match found
|
||||
|
||||
### Phase 4: Quality Assessment
|
||||
|
||||
Evaluates overall mapping quality based on critical bones:
|
||||
|
||||
```python
|
||||
critical_bones = [
|
||||
'Hips', # Root motion
|
||||
'Spine', # Torso
|
||||
'Head', # Head orientation
|
||||
'LeftArm', # Upper body
|
||||
'RightArm',
|
||||
'LeftLeg', # Lower body
|
||||
'RightLeg',
|
||||
'LeftHand', # Extremities
|
||||
'RightHand'
|
||||
]
|
||||
|
||||
if critical_mapped >= 8:
|
||||
quality = 'excellent' # Safe to auto-apply
|
||||
elif critical_mapped >= 6:
|
||||
quality = 'good' # Quick review recommended
|
||||
elif critical_mapped >= 4:
|
||||
quality = 'fair' # Thorough review required
|
||||
else:
|
||||
quality = 'poor' # Manual mapping needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Two-Phase Workflow
|
||||
|
||||
Blender Toolkit uses a two-phase workflow to ensure mapping accuracy.
|
||||
|
||||
### Phase 1: Generate & Display
|
||||
|
||||
**What Happens:**
|
||||
1. Import animation FBX into Blender
|
||||
2. Auto-generate bone mapping using fuzzy matching
|
||||
3. Calculate quality score
|
||||
4. Display mapping in Blender UI panel
|
||||
|
||||
**Blender UI Shows:**
|
||||
- Complete bone mapping table
|
||||
- Source bone → Target bone correspondence
|
||||
- Editable dropdowns for each mapping
|
||||
- Quality assessment score
|
||||
- "Auto Re-map" button (regenerate)
|
||||
- "Apply Retargeting" button (proceed to Phase 2)
|
||||
|
||||
**User Actions:**
|
||||
- Review each bone correspondence
|
||||
- Fix incorrect mappings using dropdowns
|
||||
- Use "Auto Re-map" to regenerate if needed
|
||||
- Click "Apply Retargeting" when satisfied
|
||||
|
||||
### Phase 2: Apply & Bake
|
||||
|
||||
**What Happens:**
|
||||
1. User clicks "Apply Retargeting" in Blender
|
||||
2. Creates constraint-based retargeting setup
|
||||
3. Bakes animation to keyframes
|
||||
4. Adds animation to NLA track
|
||||
5. Cleans up temporary objects
|
||||
|
||||
**Result:**
|
||||
- Fully retargeted animation on your character
|
||||
- Animation stored in NLA track
|
||||
- Original character rig unchanged
|
||||
- Ready for further editing or export
|
||||
|
||||
---
|
||||
|
||||
## Quality Assessment
|
||||
|
||||
The system automatically evaluates mapping quality.
|
||||
|
||||
### Quality Metrics
|
||||
|
||||
**Total Mappings:**
|
||||
- Number of bones successfully mapped
|
||||
- Higher is better
|
||||
|
||||
**Critical Bones Mapped:**
|
||||
- 9 essential bones for quality animation
|
||||
- Shows as ratio: "7/9 critical bones"
|
||||
|
||||
**Quality Rating:**
|
||||
| Rating | Critical Bones | Recommendation |
|
||||
|--------|----------------|----------------|
|
||||
| **Excellent** | 8-9 | Safe to auto-apply with skip-confirmation |
|
||||
| **Good** | 6-7 | Quick review recommended |
|
||||
| **Fair** | 4-5 | Thorough review required |
|
||||
| **Poor** | 0-3 | Manual mapping required |
|
||||
|
||||
### Quality Report Example
|
||||
|
||||
```json
|
||||
{
|
||||
"total_mappings": 52,
|
||||
"critical_bones_mapped": "8/9",
|
||||
"quality": "excellent",
|
||||
"summary": "52 bones mapped, 8/9 critical bones"
|
||||
}
|
||||
```
|
||||
|
||||
### When to Review Mappings
|
||||
|
||||
**Always Review If:**
|
||||
- Quality is "Fair" or "Poor"
|
||||
- Character uses non-standard rig
|
||||
- Animation has unusual requirements
|
||||
- First time using a new character rig
|
||||
|
||||
**Quick Review If:**
|
||||
- Quality is "Good"
|
||||
- Character is standard Rigify
|
||||
- Similar mappings worked before
|
||||
|
||||
**Auto-Apply If:**
|
||||
- Quality is "Excellent"
|
||||
- Using trusted custom mapping
|
||||
- Repeated animations on same character
|
||||
|
||||
---
|
||||
|
||||
## Blender UI Panel
|
||||
|
||||
The bone mapping UI panel appears in Blender's View3D sidebar.
|
||||
|
||||
### Location
|
||||
|
||||
**Path:** View3D → Sidebar (N key) → "Blender Toolkit" tab → "Bone Mapping Review"
|
||||
|
||||
### Panel Components
|
||||
|
||||
**1. Mapping Table**
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Bone Mapping Review │
|
||||
├─────────────────────────────────┤
|
||||
│ Source Bone → Target Bone │
|
||||
│ ─────────────────────────────── │
|
||||
│ Hips → [Dropdown: Hips]│
|
||||
│ Spine → [Dropdown: Spine]│
|
||||
│ LeftArm → [Dropdown: LeftArm]│
|
||||
│ ... │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**2. Quality Info**
|
||||
```
|
||||
Quality: Excellent
|
||||
Total: 52 mappings
|
||||
Critical: 8/9 bones
|
||||
```
|
||||
|
||||
**3. Action Buttons**
|
||||
- **Auto Re-map** - Regenerate mapping
|
||||
- **Apply Retargeting** - Proceed to apply
|
||||
|
||||
### Using the Panel
|
||||
|
||||
**Step 1: Open Panel**
|
||||
```
|
||||
1. Press N key in 3D View
|
||||
2. Click "Blender Toolkit" tab
|
||||
3. Find "Bone Mapping Review" panel
|
||||
```
|
||||
|
||||
**Step 2: Review Mappings**
|
||||
```
|
||||
1. Scroll through mapping table
|
||||
2. Check each source → target correspondence
|
||||
3. Pay special attention to critical bones:
|
||||
- Hips (root motion)
|
||||
- Spine chain (posture)
|
||||
- Arms and legs (animation transfer)
|
||||
```
|
||||
|
||||
**Step 3: Edit Mappings**
|
||||
```
|
||||
1. Click dropdown next to incorrect mapping
|
||||
2. Select correct target bone from list
|
||||
3. Repeat for all incorrect mappings
|
||||
```
|
||||
|
||||
**Step 4: Apply**
|
||||
```
|
||||
1. Click "Apply Retargeting" button
|
||||
2. Wait for processing (progress shown in console)
|
||||
3. Animation will be applied and baked
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mapping Patterns
|
||||
|
||||
### Rigify Rigs
|
||||
|
||||
**Standard Rigify Control Rig:**
|
||||
```
|
||||
Mixamo Rigify
|
||||
-------- ------
|
||||
Hips hips
|
||||
Spine spine_fk
|
||||
Spine1 spine_fk.001
|
||||
Spine2 spine_fk.002
|
||||
Neck neck
|
||||
Head head
|
||||
|
||||
LeftShoulder shoulder.L
|
||||
LeftArm upper_arm_fk.L
|
||||
LeftForeArm forearm_fk.L
|
||||
LeftHand hand_fk.L
|
||||
|
||||
RightShoulder shoulder.R
|
||||
RightArm upper_arm_fk.R
|
||||
RightForeArm forearm_fk.R
|
||||
RightHand hand_fk.R
|
||||
|
||||
LeftUpLeg thigh_fk.L
|
||||
LeftLeg shin_fk.L
|
||||
LeftFoot foot_fk.L
|
||||
|
||||
RightUpLeg thigh_fk.R
|
||||
RightLeg shin_fk.R
|
||||
RightFoot foot_fk.R
|
||||
```
|
||||
|
||||
### Unreal Engine (UE4/UE5)
|
||||
|
||||
**UE4 Mannequin Skeleton:**
|
||||
```
|
||||
Mixamo UE4/UE5
|
||||
-------- -------
|
||||
Hips pelvis
|
||||
Spine spine_01
|
||||
Spine1 spine_02
|
||||
Spine2 spine_03
|
||||
Neck neck_01
|
||||
Head head
|
||||
|
||||
LeftShoulder clavicle_l
|
||||
LeftArm upperarm_l
|
||||
LeftForeArm lowerarm_l
|
||||
LeftHand hand_l
|
||||
|
||||
RightShoulder clavicle_r
|
||||
RightArm upperarm_r
|
||||
RightForeArm lowerarm_r
|
||||
RightHand hand_r
|
||||
```
|
||||
|
||||
### Unity Humanoid
|
||||
|
||||
**Unity Mecanim Humanoid:**
|
||||
```
|
||||
Mixamo Unity
|
||||
-------- -----
|
||||
Hips Hips
|
||||
Spine Spine
|
||||
Spine1 Chest
|
||||
Spine2 UpperChest
|
||||
Neck Neck
|
||||
Head Head
|
||||
|
||||
LeftShoulder LeftShoulder
|
||||
LeftArm LeftUpperArm
|
||||
LeftForeArm LeftLowerArm
|
||||
LeftHand LeftHand
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Poor Quality" Mapping
|
||||
|
||||
**Symptoms:**
|
||||
- Quality assessment shows "Poor"
|
||||
- Less than 4 critical bones mapped
|
||||
|
||||
**Solutions:**
|
||||
1. **Check Rig Structure**
|
||||
- Verify character has proper armature
|
||||
- Ensure bones follow hierarchical structure
|
||||
- Check for missing bones
|
||||
|
||||
2. **Use Custom Mapping**
|
||||
- Create explicit bone mapping dictionary
|
||||
- Test with known-good mapping first
|
||||
|
||||
3. **Review Bone Names**
|
||||
- Check for unusual naming conventions
|
||||
- Look for typos or special characters
|
||||
|
||||
### Incorrect Left/Right Mapping
|
||||
|
||||
**Symptoms:**
|
||||
- Left arm mapped to right arm
|
||||
- Crossed animations
|
||||
|
||||
**Solutions:**
|
||||
1. **Check Suffix Convention**
|
||||
- Ensure consistent use of .L/.R or _l/_r
|
||||
- Verify suffix matches throughout rig
|
||||
|
||||
2. **Manual Correction**
|
||||
- Use Blender UI to swap mappings
|
||||
- Fix all left/right pairs
|
||||
|
||||
### Missing Critical Bones
|
||||
|
||||
**Symptoms:**
|
||||
- Key bones not mapped (Hips, Spine, etc.)
|
||||
- Animation doesn't transfer properly
|
||||
|
||||
**Solutions:**
|
||||
1. **Lower Threshold**
|
||||
```python
|
||||
# In custom workflow
|
||||
bone_map = fuzzy_match_bones(
|
||||
source_bones,
|
||||
target_bones,
|
||||
threshold=0.5 # Lower from default 0.6
|
||||
)
|
||||
```
|
||||
|
||||
2. **Check Bone Names**
|
||||
- Print all bone names in Blender console
|
||||
- Verify expected bones exist
|
||||
|
||||
3. **Use Explicit Mapping**
|
||||
- Map critical bones manually
|
||||
- Let auto-match handle fingers/toes
|
||||
|
||||
### Twisted or Inverted Limbs
|
||||
|
||||
**Symptoms:**
|
||||
- Arms twist incorrectly
|
||||
- Legs bend backwards
|
||||
|
||||
**Causes:**
|
||||
- Bone roll differences
|
||||
- Constraint axis misalignment
|
||||
|
||||
**Solutions:**
|
||||
1. **Check Bone Roll**
|
||||
- Compare source and target bone rolls
|
||||
- Adjust in Edit Mode if needed
|
||||
|
||||
2. **Post-Process Animation**
|
||||
- Use constraint influence
|
||||
- Add corrective keyframes
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Start Simple
|
||||
|
||||
**First Animation:**
|
||||
- Use simple animation (Idle, Walking)
|
||||
- Verify mapping quality
|
||||
- Test full body movement
|
||||
- Check for issues before complex animations
|
||||
|
||||
### 2. Review Critical Bones First
|
||||
|
||||
**Priority Order:**
|
||||
1. **Hips** - Root motion and posture
|
||||
2. **Spine Chain** - Torso movement
|
||||
3. **Shoulders** - Upper body orientation
|
||||
4. **Arms/Legs** - Limb movement
|
||||
5. **Hands/Feet** - Extremity position
|
||||
6. **Fingers/Toes** - Fine detail (optional)
|
||||
|
||||
### 3. Save Custom Mappings
|
||||
|
||||
**For Reuse:**
|
||||
```typescript
|
||||
// Save successful mapping
|
||||
const myCharacterMapping = {
|
||||
"Hips": "root_bone",
|
||||
"Spine": "torso_01",
|
||||
// ... complete mapping
|
||||
};
|
||||
|
||||
// Reuse for all animations
|
||||
await workflow.run({
|
||||
boneMapping: myCharacterMapping,
|
||||
skipConfirmation: true // Safe with known mapping
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Use Quality Threshold
|
||||
|
||||
**Decide Confirmation Strategy:**
|
||||
```typescript
|
||||
// Auto-apply only for excellent quality
|
||||
if (quality === 'excellent') {
|
||||
skipConfirmation = true;
|
||||
} else {
|
||||
skipConfirmation = false; // Review in UI
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Document Your Rigs
|
||||
|
||||
**Create Mapping Reference:**
|
||||
```markdown
|
||||
# Character: Hero
|
||||
Rig Type: Custom
|
||||
Created: 2024-01-15
|
||||
|
||||
## Bone Mapping
|
||||
Mixamo → Hero
|
||||
- Hips → root
|
||||
- Spine → spine_01
|
||||
- ...
|
||||
|
||||
## Notes
|
||||
- Uses custom spine chain (4 bones)
|
||||
- Left/Right suffix: _L / _R
|
||||
- Tested with: Walking, Running, Jumping
|
||||
```
|
||||
|
||||
### 6. Test Before Batch Processing
|
||||
|
||||
**Workflow:**
|
||||
1. Test mapping with one animation
|
||||
2. Verify quality and appearance
|
||||
3. Save mapping configuration
|
||||
4. Batch process remaining animations
|
||||
|
||||
### 7. Handle Edge Cases
|
||||
|
||||
**Preparation:**
|
||||
- Create fallback mappings for unusual rigs
|
||||
- Document special handling requirements
|
||||
- Test with varied animation types
|
||||
879
skills/references/commands-reference.md
Normal file
879
skills/references/commands-reference.md
Normal file
@@ -0,0 +1,879 @@
|
||||
# Commands Reference
|
||||
|
||||
Complete command-line interface reference for Blender Toolkit CLI.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Geometry Commands](#geometry-commands)
|
||||
- [Object Commands](#object-commands)
|
||||
- [Modifier Commands](#modifier-commands)
|
||||
- [Material Commands](#material-commands)
|
||||
- [Collection Commands](#collection-commands)
|
||||
- [Retargeting Commands](#retargeting-commands)
|
||||
- [Daemon Commands](#daemon-commands)
|
||||
- [Global Options](#global-options)
|
||||
|
||||
---
|
||||
|
||||
## Geometry Commands
|
||||
|
||||
Create and manipulate geometric primitives and meshes.
|
||||
|
||||
### create-cube
|
||||
|
||||
Create a cube primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-cube [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `-s, --size <number>` - Cube size (default: 2.0)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-cube --x 0 --y 0 --z 2 --size 1.5 --name "MyCube"
|
||||
```
|
||||
|
||||
### create-sphere
|
||||
|
||||
Create a sphere primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-sphere [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `-r, --radius <number>` - Sphere radius (default: 1.0)
|
||||
- `--segments <number>` - Number of segments (default: 32)
|
||||
- `--rings <number>` - Number of rings (default: 16)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-sphere --radius 2 --segments 64 --rings 32
|
||||
```
|
||||
|
||||
### create-cylinder
|
||||
|
||||
Create a cylinder primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-cylinder [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `-r, --radius <number>` - Cylinder radius (default: 1.0)
|
||||
- `-d, --depth <number>` - Cylinder height/depth (default: 2.0)
|
||||
- `--vertices <number>` - Number of vertices (default: 32)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-cylinder --radius 1.5 --depth 3 --vertices 64
|
||||
```
|
||||
|
||||
### create-plane
|
||||
|
||||
Create a plane primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-plane [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `-s, --size <number>` - Plane size (default: 2.0)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-plane --size 10 --name "Ground"
|
||||
```
|
||||
|
||||
### create-cone
|
||||
|
||||
Create a cone primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-cone [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `-r, --radius <number>` - Cone base radius (default: 1.0)
|
||||
- `-d, --depth <number>` - Cone height/depth (default: 2.0)
|
||||
- `--vertices <number>` - Number of vertices (default: 32)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-cone --radius 2 --depth 4
|
||||
```
|
||||
|
||||
### create-torus
|
||||
|
||||
Create a torus primitive.
|
||||
|
||||
```bash
|
||||
blender-toolkit create-torus [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-x, --x <number>` - X position (default: 0)
|
||||
- `-y, --y <number>` - Y position (default: 0)
|
||||
- `-z, --z <number>` - Z position (default: 0)
|
||||
- `--major-radius <number>` - Major radius (default: 1.0)
|
||||
- `--minor-radius <number>` - Minor radius/tube thickness (default: 0.25)
|
||||
- `--major-segments <number>` - Major segments (default: 48)
|
||||
- `--minor-segments <number>` - Minor segments (default: 12)
|
||||
- `-n, --name <string>` - Object name
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit create-torus --major-radius 3 --minor-radius 0.5
|
||||
```
|
||||
|
||||
### subdivide
|
||||
|
||||
Subdivide a mesh object to add more geometry detail.
|
||||
|
||||
```bash
|
||||
blender-toolkit subdivide [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-c, --cuts <number>` - Number of subdivision cuts (default: 1)
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit subdivide --name "Cube" --cuts 2
|
||||
```
|
||||
|
||||
### get-vertices
|
||||
|
||||
Get vertices information of an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit get-vertices [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit get-vertices --name "Sphere"
|
||||
```
|
||||
|
||||
### move-vertex
|
||||
|
||||
Move a specific vertex to a new position.
|
||||
|
||||
```bash
|
||||
blender-toolkit move-vertex [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-i, --index <number>` - Vertex index **(required)**
|
||||
- `-x, --x <number>` - New X position **(required)**
|
||||
- `-y, --y <number>` - New Y position **(required)**
|
||||
- `-z, --z <number>` - New Z position **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit move-vertex --name "Cube" --index 0 --x 1.5 --y 0 --z 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Object Commands
|
||||
|
||||
Manage and manipulate Blender objects.
|
||||
|
||||
### list-objects
|
||||
|
||||
List all objects in the scene.
|
||||
|
||||
```bash
|
||||
blender-toolkit list-objects [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-t, --type <string>` - Filter by object type (MESH, ARMATURE, CAMERA, LIGHT)
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit list-objects --type MESH
|
||||
```
|
||||
|
||||
### transform
|
||||
|
||||
Transform an object (move, rotate, scale).
|
||||
|
||||
```bash
|
||||
blender-toolkit transform [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `--loc-x <number>` - X location
|
||||
- `--loc-y <number>` - Y location
|
||||
- `--loc-z <number>` - Z location
|
||||
- `--rot-x <number>` - X rotation (radians)
|
||||
- `--rot-y <number>` - Y rotation (radians)
|
||||
- `--rot-z <number>` - Z rotation (radians)
|
||||
- `--scale-x <number>` - X scale
|
||||
- `--scale-y <number>` - Y scale
|
||||
- `--scale-z <number>` - Z scale
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit transform --name "Cube" --loc-x 5 --loc-y 0 --loc-z 2 --scale-x 2
|
||||
```
|
||||
|
||||
### duplicate
|
||||
|
||||
Duplicate an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit duplicate [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Source object name **(required)**
|
||||
- `--new-name <string>` - New object name
|
||||
- `-x, --x <number>` - X position for duplicate
|
||||
- `-y, --y <number>` - Y position for duplicate
|
||||
- `-z, --z <number>` - Z position for duplicate
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit duplicate --name "Cube" --new-name "Cube.001" --x 3
|
||||
```
|
||||
|
||||
### delete
|
||||
|
||||
Delete an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit delete [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit delete --name "Cube.001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modifier Commands
|
||||
|
||||
Add and manage modifiers on objects.
|
||||
|
||||
### add-modifier
|
||||
|
||||
Add a modifier to an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit add-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-t, --type <string>` - Modifier type (SUBSURF, MIRROR, ARRAY, BEVEL, etc.) **(required)**
|
||||
- `--mod-name <string>` - Modifier name
|
||||
- `--levels <number>` - Subdivision levels (for SUBSURF)
|
||||
- `--render-levels <number>` - Render levels (for SUBSURF)
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Common Modifier Types:**
|
||||
- `SUBSURF` - Subdivision Surface
|
||||
- `MIRROR` - Mirror
|
||||
- `ARRAY` - Array
|
||||
- `BEVEL` - Bevel
|
||||
- `SOLIDIFY` - Solidify
|
||||
- `BOOLEAN` - Boolean
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit add-modifier --name "Cube" --type SUBSURF --levels 2
|
||||
```
|
||||
|
||||
### apply-modifier
|
||||
|
||||
Apply a modifier to an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit apply-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit apply-modifier --name "Cube" --modifier "Subdivision"
|
||||
```
|
||||
|
||||
### list-modifiers
|
||||
|
||||
List all modifiers on an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit list-modifiers [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit list-modifiers --name "Cube"
|
||||
```
|
||||
|
||||
### remove-modifier
|
||||
|
||||
Remove a modifier from an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit remove-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit remove-modifier --name "Cube" --modifier "Subdivision"
|
||||
```
|
||||
|
||||
### toggle-modifier
|
||||
|
||||
Toggle modifier visibility.
|
||||
|
||||
```bash
|
||||
blender-toolkit toggle-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `--viewport <boolean>` - Viewport visibility (true/false)
|
||||
- `--render <boolean>` - Render visibility (true/false)
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit toggle-modifier --name "Cube" --modifier "Subdivision" --viewport false
|
||||
```
|
||||
|
||||
### modify-modifier
|
||||
|
||||
Modify modifier properties.
|
||||
|
||||
```bash
|
||||
blender-toolkit modify-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `--levels <number>` - Subdivision levels
|
||||
- `--render-levels <number>` - Render levels
|
||||
- `--width <number>` - Bevel width
|
||||
- `--segments <number>` - Bevel segments
|
||||
- `--count <number>` - Array count
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit modify-modifier --name "Cube" --modifier "Subdivision" --levels 3
|
||||
```
|
||||
|
||||
### get-modifier-info
|
||||
|
||||
Get detailed modifier information.
|
||||
|
||||
```bash
|
||||
blender-toolkit get-modifier-info [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit get-modifier-info --name "Cube" --modifier "Subdivision"
|
||||
```
|
||||
|
||||
### reorder-modifier
|
||||
|
||||
Reorder modifier in the modifier stack.
|
||||
|
||||
```bash
|
||||
blender-toolkit reorder-modifier [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-n, --name <string>` - Object name **(required)**
|
||||
- `-m, --modifier <string>` - Modifier name **(required)**
|
||||
- `-d, --direction <string>` - Direction (UP or DOWN) **(required)**
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit reorder-modifier --name "Cube" --modifier "Subdivision" --direction UP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Material Commands
|
||||
|
||||
Create and manage materials.
|
||||
|
||||
### material create
|
||||
|
||||
Create a new material.
|
||||
|
||||
```bash
|
||||
blender-toolkit material create [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--name <name>` - Material name **(required)**
|
||||
- `--no-nodes` - Disable node-based material (default: enabled)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material create --name "RedMaterial"
|
||||
```
|
||||
|
||||
### material list
|
||||
|
||||
List all materials in the scene.
|
||||
|
||||
```bash
|
||||
blender-toolkit material list
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material list
|
||||
```
|
||||
|
||||
### material delete
|
||||
|
||||
Delete a material.
|
||||
|
||||
```bash
|
||||
blender-toolkit material delete [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--name <name>` - Material name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material delete --name "RedMaterial"
|
||||
```
|
||||
|
||||
### material assign
|
||||
|
||||
Assign a material to an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit material assign [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--object <name>` - Object name **(required)**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
- `--slot <index>` - Material slot index (default: 0)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material assign --object "Cube" --material "RedMaterial"
|
||||
```
|
||||
|
||||
### material list-object
|
||||
|
||||
List materials assigned to an object.
|
||||
|
||||
```bash
|
||||
blender-toolkit material list-object [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--object <name>` - Object name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material list-object --object "Cube"
|
||||
```
|
||||
|
||||
### material set-color
|
||||
|
||||
Set material base color.
|
||||
|
||||
```bash
|
||||
blender-toolkit material set-color [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
- `--r <value>` - Red (0-1) **(required)**
|
||||
- `--g <value>` - Green (0-1) **(required)**
|
||||
- `--b <value>` - Blue (0-1) **(required)**
|
||||
- `--a <value>` - Alpha (0-1) (default: 1.0)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material set-color --material "RedMaterial" --r 1.0 --g 0.0 --b 0.0
|
||||
```
|
||||
|
||||
### material set-metallic
|
||||
|
||||
Set material metallic value.
|
||||
|
||||
```bash
|
||||
blender-toolkit material set-metallic [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
- `--value <value>` - Metallic value (0-1) **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material set-metallic --material "MetalMaterial" --value 1.0
|
||||
```
|
||||
|
||||
### material set-roughness
|
||||
|
||||
Set material roughness value.
|
||||
|
||||
```bash
|
||||
blender-toolkit material set-roughness [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
- `--value <value>` - Roughness value (0-1) **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material set-roughness --material "MetalMaterial" --value 0.2
|
||||
```
|
||||
|
||||
### material set-emission
|
||||
|
||||
Set material emission.
|
||||
|
||||
```bash
|
||||
blender-toolkit material set-emission [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
- `--r <value>` - Red (0-1) **(required)**
|
||||
- `--g <value>` - Green (0-1) **(required)**
|
||||
- `--b <value>` - Blue (0-1) **(required)**
|
||||
- `--strength <value>` - Emission strength (default: 1.0)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material set-emission --material "GlowMaterial" --r 0 --g 1 --b 0 --strength 5
|
||||
```
|
||||
|
||||
### material get-properties
|
||||
|
||||
Get material properties.
|
||||
|
||||
```bash
|
||||
blender-toolkit material get-properties [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--material <name>` - Material name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit material get-properties --material "RedMaterial"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Collection Commands
|
||||
|
||||
Organize objects into collections.
|
||||
|
||||
### collection create
|
||||
|
||||
Create a new collection.
|
||||
|
||||
```bash
|
||||
blender-toolkit collection create [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--name <name>` - Collection name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit collection create --name "Props"
|
||||
```
|
||||
|
||||
### collection list
|
||||
|
||||
List all collections.
|
||||
|
||||
```bash
|
||||
blender-toolkit collection list
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit collection list
|
||||
```
|
||||
|
||||
### collection add-object
|
||||
|
||||
Add an object to a collection.
|
||||
|
||||
```bash
|
||||
blender-toolkit collection add-object [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--object <name>` - Object name **(required)**
|
||||
- `--collection <name>` - Collection name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit collection add-object --object "Cube" --collection "Props"
|
||||
```
|
||||
|
||||
### collection remove-object
|
||||
|
||||
Remove an object from a collection.
|
||||
|
||||
```bash
|
||||
blender-toolkit collection remove-object [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--object <name>` - Object name **(required)**
|
||||
- `--collection <name>` - Collection name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit collection remove-object --object "Cube" --collection "Props"
|
||||
```
|
||||
|
||||
### collection delete
|
||||
|
||||
Delete a collection.
|
||||
|
||||
```bash
|
||||
blender-toolkit collection delete [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--name <name>` - Collection name **(required)**
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit collection delete --name "Props"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Retargeting Commands
|
||||
|
||||
Animation retargeting from Mixamo to custom rigs.
|
||||
|
||||
### retarget
|
||||
|
||||
Retarget animation from Mixamo to your character.
|
||||
|
||||
```bash
|
||||
blender-toolkit retarget [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-t, --target <string>` - Target character armature name **(required)**
|
||||
- `-f, --file <string>` - Animation file path (FBX or DAE) **(required)**
|
||||
- `-n, --name <string>` - Animation name for NLA track
|
||||
- `-m, --mapping <string>` - Bone mapping mode (auto, mixamo_to_rigify, custom) (default: auto)
|
||||
- `--skip-confirmation` - Skip bone mapping confirmation (default: false)
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
- `-o, --output <string>` - Output directory
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit retarget --target "Hero" --file "./Walking.fbx" --name "Walking"
|
||||
```
|
||||
|
||||
**With Auto Confirmation:**
|
||||
```bash
|
||||
blender-toolkit retarget --target "Hero" --file "./Walking.fbx" --skip-confirmation
|
||||
```
|
||||
|
||||
### mixamo-help
|
||||
|
||||
Show Mixamo download instructions and popular animations.
|
||||
|
||||
```bash
|
||||
blender-toolkit mixamo-help [animation-name]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `[animation-name]` - Optional: Get specific animation instructions
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Show all popular animations and general instructions
|
||||
blender-toolkit mixamo-help
|
||||
|
||||
# Show instructions for specific animation
|
||||
blender-toolkit mixamo-help Walking
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Daemon Commands
|
||||
|
||||
Manage Blender WebSocket server daemon.
|
||||
|
||||
### daemon-start
|
||||
|
||||
Start the Blender WebSocket server.
|
||||
|
||||
```bash
|
||||
blender-toolkit daemon-start [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-p, --port <number>` - Port number (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit daemon-start --port 9400
|
||||
```
|
||||
|
||||
### daemon-stop
|
||||
|
||||
Stop the Blender WebSocket server.
|
||||
|
||||
```bash
|
||||
blender-toolkit daemon-stop [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-p, --port <number>` - Port number (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit daemon-stop
|
||||
```
|
||||
|
||||
### daemon-status
|
||||
|
||||
Check Blender WebSocket server status.
|
||||
|
||||
```bash
|
||||
blender-toolkit daemon-status [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-p, --port <number>` - Port number (default: 9400)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
blender-toolkit daemon-status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Global Options
|
||||
|
||||
Options available for all commands:
|
||||
|
||||
- `-p, --port <number>` - Blender WebSocket port (default: 9400)
|
||||
- `-h, --help` - Display help for command
|
||||
- `-V, --version` - Output the version number
|
||||
|
||||
---
|
||||
|
||||
## Port Range
|
||||
|
||||
Blender Toolkit uses port range **9400-9500** for WebSocket connections.
|
||||
|
||||
- Default port: **9400**
|
||||
- Browser Pilot uses: **9222-9322** (no conflict)
|
||||
- Multiple projects can run simultaneously with different ports
|
||||
- Ports are auto-assigned and persisted in project configuration
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Use `--help` for Detailed Options:**
|
||||
```bash
|
||||
blender-toolkit <command> --help
|
||||
```
|
||||
|
||||
2. **Port Conflicts:**
|
||||
- If default port 9400 is in use, specify a different port
|
||||
- Configuration persists across sessions
|
||||
|
||||
3. **Object Names are Case-Sensitive:**
|
||||
- Use exact names as they appear in Blender
|
||||
|
||||
4. **WebSocket Connection:**
|
||||
- Ensure Blender addon is enabled and server is started
|
||||
- Check port number matches between CLI and addon
|
||||
|
||||
5. **Batch Operations:**
|
||||
- Use shell scripts to combine multiple commands
|
||||
- Example: Create multiple objects with different positions
|
||||
817
skills/references/workflow-guide.md
Normal file
817
skills/references/workflow-guide.md
Normal file
@@ -0,0 +1,817 @@
|
||||
# Workflow Guide
|
||||
|
||||
Detailed guide for animation retargeting workflows using Blender Toolkit.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Complete Retargeting Workflow](#complete-retargeting-workflow)
|
||||
- [Mixamo Download Workflow](#mixamo-download-workflow)
|
||||
- [Two-Phase Confirmation Workflow](#two-phase-confirmation-workflow)
|
||||
- [Batch Processing Workflow](#batch-processing-workflow)
|
||||
- [Multi-Project Workflow](#multi-project-workflow)
|
||||
- [Advanced Workflows](#advanced-workflows)
|
||||
- [Common Scenarios](#common-scenarios)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Blender Toolkit provides a complete workflow for retargeting Mixamo animations to custom character rigs in Blender.
|
||||
|
||||
**Core Workflow Steps:**
|
||||
1. Prepare character rig in Blender
|
||||
2. Download animation from Mixamo
|
||||
3. Connect to Blender via WebSocket
|
||||
4. Import and auto-map bones
|
||||
5. Review mapping in Blender UI
|
||||
6. Confirm and apply retargeting
|
||||
7. Animation baked to NLA track
|
||||
|
||||
**Key Features:**
|
||||
- WebSocket-based real-time control
|
||||
- Two-phase confirmation workflow
|
||||
- Automatic bone mapping with UI review
|
||||
- Quality assessment
|
||||
- Multi-project support
|
||||
- Session hooks for auto-initialization
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. Blender Setup
|
||||
|
||||
**Install and Configure:**
|
||||
```
|
||||
1. Install Blender 4.0 or higher (2023+)
|
||||
2. Install Python addon:
|
||||
Method 1 (Recommended): Install from ZIP
|
||||
- Edit → Preferences → Add-ons → Install
|
||||
- Select: .blender-toolkit/blender-toolkit-addon-v*.zip
|
||||
- Enable "Blender Toolkit WebSocket Server"
|
||||
|
||||
Method 2: Install from Source
|
||||
- Edit → Preferences → Add-ons → Install
|
||||
- Select: plugins/blender-toolkit/skills/addon/__init__.py
|
||||
- Enable "Blender Toolkit WebSocket Server"
|
||||
3. Start WebSocket server:
|
||||
- View3D → Sidebar (N key) → "Blender Toolkit" tab
|
||||
- Click "Start Server"
|
||||
- Default port: 9400
|
||||
```
|
||||
|
||||
### 2. Character Rig Requirements
|
||||
|
||||
**Your Character Must Have:**
|
||||
- ✅ Armature with properly set up bones
|
||||
- ✅ Standard or Rigify-compatible bone naming (recommended)
|
||||
- ✅ Proper parent-child bone hierarchy
|
||||
- ✅ Character loaded in current Blender scene
|
||||
|
||||
**Supported Rig Types:**
|
||||
- Rigify control rigs ⭐ (best support)
|
||||
- Custom rigs with standard naming
|
||||
- Game engine rigs (UE4/UE5, Unity)
|
||||
- Any armature with clear bone hierarchy
|
||||
|
||||
### 3. Local Scripts
|
||||
|
||||
**Auto-Initialized by SessionStart Hook:**
|
||||
- TypeScript source copied to `.blender-toolkit/skills/scripts/`
|
||||
- Dependencies installed (`npm install`)
|
||||
- Scripts built (`npm run build`)
|
||||
- CLI wrapper created (`.blender-toolkit/bt.js`)
|
||||
|
||||
**Manual Check (if needed):**
|
||||
```bash
|
||||
# Verify scripts are built
|
||||
ls .blender-toolkit/skills/scripts/dist
|
||||
|
||||
# Rebuild if necessary
|
||||
cd .blender-toolkit/skills/scripts
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Retargeting Workflow
|
||||
|
||||
### Step 1: Prepare Character
|
||||
|
||||
**In Blender:**
|
||||
```
|
||||
1. Open your character model
|
||||
2. Verify armature exists and is rigged
|
||||
3. Note the exact armature name (case-sensitive)
|
||||
4. Check bone structure (Edit Mode):
|
||||
- Proper hierarchy (Hips → Spine → etc.)
|
||||
- Standard naming (preferred)
|
||||
5. Leave Blender open with character visible
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Use descriptive armature name: "HeroRig", "PlayerModel"
|
||||
- Avoid generic names: "Armature", "Armature.001"
|
||||
- Ensure character is in rest pose
|
||||
|
||||
### Step 2: Download Mixamo Animation
|
||||
|
||||
**Option A: User Has FBX File**
|
||||
- User provides path to downloaded FBX
|
||||
- Skip to Step 3
|
||||
|
||||
**Option B: User Needs to Download**
|
||||
```bash
|
||||
# Show download instructions
|
||||
blender-toolkit mixamo-help Walking
|
||||
```
|
||||
|
||||
**Download Steps:**
|
||||
1. Go to Mixamo.com
|
||||
2. Search for animation (e.g., "Walking")
|
||||
3. Configure settings:
|
||||
- Format: FBX (.fbx)
|
||||
- Skin: Without Skin
|
||||
- FPS: 30
|
||||
- Keyframe Reduction: None
|
||||
4. Click "Download"
|
||||
5. Note download path
|
||||
|
||||
**Recommended Settings:**
|
||||
```
|
||||
Format: FBX (.fbx)
|
||||
Skin: Without Skin
|
||||
Frame Rate: 30 fps
|
||||
Keyframe Reduction: None
|
||||
```
|
||||
|
||||
### Step 3: Verify Blender Connection
|
||||
|
||||
**Check WebSocket Server:**
|
||||
```bash
|
||||
blender-toolkit daemon-status
|
||||
```
|
||||
|
||||
**If Not Running:**
|
||||
```
|
||||
1. Open Blender
|
||||
2. Press N key in 3D View
|
||||
3. Click "Blender Toolkit" tab
|
||||
4. Click "Start Server"
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✅ Blender WebSocket server is running on port 9400
|
||||
```
|
||||
|
||||
### Step 4: Execute Retargeting
|
||||
|
||||
**Basic Command:**
|
||||
```bash
|
||||
blender-toolkit retarget \
|
||||
--target "HeroRig" \
|
||||
--file "./downloads/Walking.fbx" \
|
||||
--name "Walking"
|
||||
```
|
||||
|
||||
**What Happens:**
|
||||
```
|
||||
🎬 Starting animation retargeting workflow...
|
||||
|
||||
[1/6] Connecting to Blender...
|
||||
✅ Connected to Blender on port 9400
|
||||
|
||||
[2/6] Importing animation FBX...
|
||||
✅ Animation imported: 30 frames
|
||||
|
||||
[3/6] Analyzing bone structure...
|
||||
✅ Source bones: 65 (Mixamo)
|
||||
✅ Target bones: 52 (HeroRig)
|
||||
|
||||
[4/6] Auto-generating bone mapping...
|
||||
✅ Mapped 48 bones
|
||||
✅ Quality: Excellent (8/9 critical bones)
|
||||
|
||||
[5/6] Displaying mapping in Blender UI...
|
||||
✅ Mapping displayed in "Bone Mapping Review" panel
|
||||
|
||||
⏸ Workflow paused for user review
|
||||
👉 Please review the bone mapping in Blender
|
||||
👉 Edit any incorrect mappings
|
||||
👉 Click "Apply Retargeting" when ready
|
||||
```
|
||||
|
||||
### Step 5: Review Mapping in Blender
|
||||
|
||||
**Open Mapping Panel:**
|
||||
```
|
||||
1. Press N key in 3D View
|
||||
2. Go to "Blender Toolkit" tab
|
||||
3. Find "Bone Mapping Review" panel
|
||||
```
|
||||
|
||||
**Review Checklist:**
|
||||
- [ ] Hips mapped correctly (root motion)
|
||||
- [ ] Spine chain mapped in order
|
||||
- [ ] Left/Right arms not swapped
|
||||
- [ ] Left/Right legs not swapped
|
||||
- [ ] Hands and feet mapped
|
||||
- [ ] Head and neck mapped
|
||||
|
||||
**Edit If Needed:**
|
||||
- Click dropdown next to incorrect mapping
|
||||
- Select correct bone from list
|
||||
- Repeat for all issues
|
||||
|
||||
### Step 6: Apply Retargeting
|
||||
|
||||
**In Blender:**
|
||||
```
|
||||
1. After reviewing mappings
|
||||
2. Click "Apply Retargeting" button
|
||||
3. Wait for processing
|
||||
```
|
||||
|
||||
**Processing Steps:**
|
||||
```
|
||||
[6/6] Applying retargeting...
|
||||
- Creating constraint setup...
|
||||
- Baking animation to keyframes...
|
||||
- Adding to NLA track...
|
||||
- Cleaning up temporary objects...
|
||||
|
||||
✅ Animation retargeting completed successfully!
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- Animation applied to your character
|
||||
- Stored in NLA track named "Walking"
|
||||
- Original rig unchanged
|
||||
- Ready for editing or export
|
||||
|
||||
---
|
||||
|
||||
## Mixamo Download Workflow
|
||||
|
||||
Step-by-step guide for downloading animations from Mixamo.
|
||||
|
||||
### Get Download Instructions
|
||||
|
||||
**Show Popular Animations:**
|
||||
```bash
|
||||
blender-toolkit mixamo-help
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
📚 Popular Mixamo Animations:
|
||||
|
||||
Locomotion:
|
||||
• Walking
|
||||
• Running
|
||||
• Jogging
|
||||
• Sprinting
|
||||
• Crouching
|
||||
|
||||
Combat:
|
||||
• Punching
|
||||
• Kicking
|
||||
• Sword Slash
|
||||
• Rifle Aim
|
||||
• Pistol Fire
|
||||
|
||||
Idle:
|
||||
• Idle
|
||||
• Breathing Idle
|
||||
• Standing Idle
|
||||
```
|
||||
|
||||
**Get Specific Instructions:**
|
||||
```bash
|
||||
blender-toolkit mixamo-help Walking
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
📥 Mixamo Download Instructions for "Walking"
|
||||
|
||||
1. Go to https://www.mixamo.com
|
||||
2. Sign in or create account (free)
|
||||
3. Search for "Walking" in the search bar
|
||||
4. Select the animation you want
|
||||
5. Click "Download" button
|
||||
6. Configure download settings:
|
||||
✅ Format: FBX (.fbx)
|
||||
✅ Skin: Without Skin
|
||||
✅ Frame Rate: 30 fps
|
||||
✅ Keyframe Reduction: None
|
||||
7. Click "Download"
|
||||
8. Note the downloaded file path
|
||||
|
||||
⚙️ Recommended Settings:
|
||||
|
||||
Format: FBX (.fbx)
|
||||
Skin: Without Skin
|
||||
Frame Rate: 30 fps
|
||||
Keyframe Reduction: None
|
||||
```
|
||||
|
||||
### Why "Without Skin"
|
||||
|
||||
**Reasons:**
|
||||
- We only need animation data, not mesh
|
||||
- Reduces file size significantly
|
||||
- Faster import into Blender
|
||||
- Cleaner workflow (no extra objects to delete)
|
||||
|
||||
**What It Means:**
|
||||
- FBX contains only skeleton and keyframes
|
||||
- No mesh/geometry included
|
||||
- Perfect for retargeting to existing characters
|
||||
|
||||
---
|
||||
|
||||
## Two-Phase Confirmation Workflow
|
||||
|
||||
The workflow pauses after mapping generation for user review.
|
||||
|
||||
### Phase 1: Generate and Display
|
||||
|
||||
**Automatic Steps:**
|
||||
```
|
||||
1. Import FBX [Auto]
|
||||
2. Extract bone structure [Auto]
|
||||
3. Generate mapping [Auto]
|
||||
4. Display in UI [Auto]
|
||||
5. Pause for review [Manual]
|
||||
```
|
||||
|
||||
**User Actions:**
|
||||
- Review mapping quality
|
||||
- Check critical bones
|
||||
- Edit incorrect mappings
|
||||
- Confirm readiness
|
||||
|
||||
### Phase 2: Apply and Bake
|
||||
|
||||
**Triggered by User:**
|
||||
- User clicks "Apply Retargeting" in Blender
|
||||
|
||||
**Automatic Steps:**
|
||||
```
|
||||
6. Create constraints [Auto]
|
||||
7. Bake to keyframes [Auto]
|
||||
8. Add to NLA track [Auto]
|
||||
9. Cleanup [Auto]
|
||||
10. Complete [Auto]
|
||||
```
|
||||
|
||||
### Skipping Confirmation
|
||||
|
||||
**For Trusted Mappings:**
|
||||
```bash
|
||||
blender-toolkit retarget \
|
||||
--target "HeroRig" \
|
||||
--file "./Walking.fbx" \
|
||||
--skip-confirmation
|
||||
```
|
||||
|
||||
**When to Skip:**
|
||||
- Excellent quality mapping (8-9 critical bones)
|
||||
- Repeated animations on same character
|
||||
- Using proven custom mapping
|
||||
- Batch processing with known-good setup
|
||||
|
||||
**When NOT to Skip:**
|
||||
- First animation on new character
|
||||
- Unknown rig structure
|
||||
- Fair or Poor quality mapping
|
||||
- Complex or unusual animations
|
||||
|
||||
---
|
||||
|
||||
## Batch Processing Workflow
|
||||
|
||||
Process multiple animations efficiently.
|
||||
|
||||
### Step 1: Test Single Animation
|
||||
|
||||
**Verify Setup:**
|
||||
```bash
|
||||
# Test with one animation first
|
||||
blender-toolkit retarget \
|
||||
--target "HeroRig" \
|
||||
--file "./Walking.fbx" \
|
||||
--name "Walking"
|
||||
```
|
||||
|
||||
**Check Results:**
|
||||
- Animation looks correct
|
||||
- No twisted limbs
|
||||
- Left/Right not swapped
|
||||
- Quality is excellent
|
||||
|
||||
### Step 2: Extract Mapping
|
||||
|
||||
**Save Successful Mapping:**
|
||||
```typescript
|
||||
// After successful test, save the mapping
|
||||
// Check Blender console or logs for generated mapping
|
||||
const heroRigMapping = {
|
||||
"Hips": "root",
|
||||
"Spine": "spine_01",
|
||||
"Spine1": "spine_02",
|
||||
// ... complete mapping
|
||||
};
|
||||
|
||||
// Save to file for reuse
|
||||
fs.writeFileSync('./hero-mapping.json', JSON.stringify(heroRigMapping));
|
||||
```
|
||||
|
||||
### Step 3: Batch Process
|
||||
|
||||
**Shell Script Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# batch-retarget.sh
|
||||
|
||||
ANIMATIONS=(
|
||||
"Walking"
|
||||
"Running"
|
||||
"Jumping"
|
||||
"Idle"
|
||||
"Punching"
|
||||
)
|
||||
|
||||
for anim in "${ANIMATIONS[@]}"; do
|
||||
echo "Processing ${anim}..."
|
||||
blender-toolkit retarget \
|
||||
--target "HeroRig" \
|
||||
--file "./animations/${anim}.fbx" \
|
||||
--name "${anim}" \
|
||||
--skip-confirmation
|
||||
echo "✅ ${anim} completed"
|
||||
done
|
||||
|
||||
echo "🎉 All animations processed!"
|
||||
```
|
||||
|
||||
**TypeScript Example:**
|
||||
```typescript
|
||||
// batch-retarget.ts
|
||||
const animations = [
|
||||
'Walking', 'Running', 'Jumping',
|
||||
'Idle', 'Punching'
|
||||
];
|
||||
|
||||
const workflow = new AnimationRetargetingWorkflow();
|
||||
|
||||
for (const anim of animations) {
|
||||
await workflow.run({
|
||||
targetCharacterArmature: 'HeroRig',
|
||||
animationFilePath: `./animations/${anim}.fbx`,
|
||||
animationName: anim,
|
||||
boneMapping: heroRigMapping, // Reuse saved mapping
|
||||
skipConfirmation: true
|
||||
});
|
||||
|
||||
console.log(`✅ ${anim} completed`);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Project Workflow
|
||||
|
||||
Work with multiple Blender projects simultaneously.
|
||||
|
||||
### Port Management
|
||||
|
||||
**Default Behavior:**
|
||||
- First project: Port 9400
|
||||
- Second project: Port 9401
|
||||
- Third project: Port 9402
|
||||
- Auto-increments for each project
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
// ~/.claude/plugins/.../blender-config.json
|
||||
{
|
||||
"projects": {
|
||||
"/path/to/project-a": {
|
||||
"port": 9400,
|
||||
"lastUsed": "2024-01-15T10:30:00Z"
|
||||
},
|
||||
"/path/to/project-b": {
|
||||
"port": 9401,
|
||||
"lastUsed": "2024-01-15T11:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
**Project A:**
|
||||
```bash
|
||||
cd /path/to/project-a
|
||||
|
||||
# Start Blender with port 9400
|
||||
# Run retargeting
|
||||
blender-toolkit retarget \
|
||||
--target "CharacterA" \
|
||||
--file "./Walking.fbx" \
|
||||
--port 9400
|
||||
```
|
||||
|
||||
**Project B (Simultaneously):**
|
||||
```bash
|
||||
cd /path/to/project-b
|
||||
|
||||
# Start Blender with port 9401
|
||||
# Run retargeting
|
||||
blender-toolkit retarget \
|
||||
--target "CharacterB" \
|
||||
--file "./Running.fbx" \
|
||||
--port 9401
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- No port conflicts
|
||||
- Simultaneous processing
|
||||
- Independent configurations
|
||||
- Separate log files
|
||||
|
||||
---
|
||||
|
||||
## Advanced Workflows
|
||||
|
||||
### Custom Bone Mapping Workflow
|
||||
|
||||
**For Non-Standard Rigs:**
|
||||
|
||||
**Step 1: Analyze Bones**
|
||||
```bash
|
||||
# List all bones in target rig
|
||||
blender-toolkit list-objects --type ARMATURE
|
||||
blender-toolkit get-bones --armature "MyRig"
|
||||
```
|
||||
|
||||
**Step 2: Create Mapping**
|
||||
```typescript
|
||||
// custom-mapping.ts
|
||||
export const myRigMapping = {
|
||||
// Core
|
||||
"Hips": "pelvis",
|
||||
"Spine": "spine_01",
|
||||
"Spine1": "spine_02",
|
||||
"Spine2": "chest",
|
||||
"Neck": "neck_01",
|
||||
"Head": "head",
|
||||
|
||||
// Left Arm
|
||||
"LeftShoulder": "clavicle_L",
|
||||
"LeftArm": "upperarm_L",
|
||||
"LeftForeArm": "forearm_L",
|
||||
"LeftHand": "hand_L",
|
||||
|
||||
// Right Arm
|
||||
"RightShoulder": "clavicle_R",
|
||||
"RightArm": "upperarm_R",
|
||||
"RightForeArm": "forearm_R",
|
||||
"RightHand": "hand_R",
|
||||
|
||||
// Add remaining bones...
|
||||
};
|
||||
```
|
||||
|
||||
**Step 3: Use Custom Mapping**
|
||||
```typescript
|
||||
import { myRigMapping } from './custom-mapping';
|
||||
|
||||
await workflow.run({
|
||||
targetCharacterArmature: 'MyRig',
|
||||
animationFilePath: './Walking.fbx',
|
||||
boneMapping: myRigMapping,
|
||||
skipConfirmation: true
|
||||
});
|
||||
```
|
||||
|
||||
### Animation Library Workflow
|
||||
|
||||
**Organize Animation Library:**
|
||||
|
||||
**Directory Structure:**
|
||||
```
|
||||
animations/
|
||||
├── locomotion/
|
||||
│ ├── walking.fbx
|
||||
│ ├── running.fbx
|
||||
│ └── jumping.fbx
|
||||
├── combat/
|
||||
│ ├── punch.fbx
|
||||
│ ├── kick.fbx
|
||||
│ └── block.fbx
|
||||
└── idle/
|
||||
├── idle.fbx
|
||||
└── breathing.fbx
|
||||
```
|
||||
|
||||
**Batch Import Script:**
|
||||
```typescript
|
||||
// import-library.ts
|
||||
const library = {
|
||||
locomotion: ['walking', 'running', 'jumping'],
|
||||
combat: ['punch', 'kick', 'block'],
|
||||
idle: ['idle', 'breathing']
|
||||
};
|
||||
|
||||
for (const [category, animations] of Object.entries(library)) {
|
||||
for (const anim of animations) {
|
||||
await workflow.run({
|
||||
targetCharacterArmature: 'Hero',
|
||||
animationFilePath: `./animations/${category}/${anim}.fbx`,
|
||||
animationName: `${category}_${anim}`,
|
||||
boneMapping: 'auto',
|
||||
skipConfirmation: false // Review each category first
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: First-Time User
|
||||
|
||||
**Goal:** Retarget first Mixamo animation to custom character
|
||||
|
||||
**Steps:**
|
||||
1. Download animation from Mixamo
|
||||
2. Start Blender with character
|
||||
3. Enable and start WebSocket addon
|
||||
4. Run retarget command
|
||||
5. Review mapping in UI
|
||||
6. Apply retargeting
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Get download instructions
|
||||
blender-toolkit mixamo-help Walking
|
||||
|
||||
# After downloading...
|
||||
blender-toolkit retarget \
|
||||
--target "MyCharacter" \
|
||||
--file "./Walking.fbx"
|
||||
```
|
||||
|
||||
### Scenario 2: Rigify User
|
||||
|
||||
**Goal:** Fast workflow for standard Rigify rig
|
||||
|
||||
**Steps:**
|
||||
1. Download animation
|
||||
2. Run with Rigify preset
|
||||
3. Auto-apply (skip confirmation)
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
blender-toolkit retarget \
|
||||
--target "MyRigifyCharacter" \
|
||||
--file "./Walking.fbx" \
|
||||
--mapping mixamo_to_rigify \
|
||||
--skip-confirmation
|
||||
```
|
||||
|
||||
### Scenario 3: Game Developer
|
||||
|
||||
**Goal:** Import 50 animations for game character
|
||||
|
||||
**Steps:**
|
||||
1. Test one animation
|
||||
2. Save mapping configuration
|
||||
3. Batch process all animations
|
||||
4. Export to game engine
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Test first
|
||||
blender-toolkit retarget \
|
||||
--target "GameCharacter" \
|
||||
--file "./test.fbx"
|
||||
|
||||
# Batch process
|
||||
./batch-import.sh
|
||||
```
|
||||
|
||||
### Scenario 4: Studio Pipeline
|
||||
|
||||
**Goal:** Integrate into production pipeline
|
||||
|
||||
**Setup:**
|
||||
- Custom wrapper scripts
|
||||
- CI/CD integration
|
||||
- Automated testing
|
||||
- Quality validation
|
||||
|
||||
**Pipeline:**
|
||||
```yaml
|
||||
# .github/workflows/animation-pipeline.yml
|
||||
jobs:
|
||||
retarget:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Setup Blender
|
||||
run: install-blender
|
||||
|
||||
- name: Start WebSocket
|
||||
run: start-blender-daemon
|
||||
|
||||
- name: Retarget Animations
|
||||
run: |
|
||||
for fbx in animations/*.fbx; do
|
||||
blender-toolkit retarget \
|
||||
--target "$CHARACTER" \
|
||||
--file "$fbx" \
|
||||
--skip-confirmation
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**Problem:** "Failed to connect to Blender"
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# 1. Check if Blender is running
|
||||
ps aux | grep -i blender
|
||||
|
||||
# 2. Verify addon is enabled
|
||||
# In Blender: Edit → Preferences → Add-ons → Search "Blender Toolkit"
|
||||
|
||||
# 3. Check server status
|
||||
blender-toolkit daemon-status
|
||||
|
||||
# 4. Restart server
|
||||
# In Blender: Click "Stop Server", then "Start Server"
|
||||
|
||||
# 5. Try different port
|
||||
blender-toolkit retarget --port 9401 ...
|
||||
```
|
||||
|
||||
### Import Issues
|
||||
|
||||
**Problem:** "Failed to import FBX file"
|
||||
|
||||
**Solutions:**
|
||||
- Verify file path is correct
|
||||
- Check FBX format (should be Binary, not ASCII)
|
||||
- Ensure file is not corrupted
|
||||
- Try re-downloading from Mixamo
|
||||
|
||||
### Mapping Issues
|
||||
|
||||
**Problem:** "Poor quality mapping"
|
||||
|
||||
**Solutions:**
|
||||
1. Lower threshold:
|
||||
```typescript
|
||||
// Custom workflow
|
||||
threshold: 0.5 // Default is 0.6
|
||||
```
|
||||
|
||||
2. Use custom mapping for critical bones
|
||||
|
||||
3. Review bone names in Blender:
|
||||
- Edit Mode → Show bone names
|
||||
- Check for typos or unusual names
|
||||
|
||||
### Animation Issues
|
||||
|
||||
**Problem:** "Animation looks wrong"
|
||||
|
||||
**Solutions:**
|
||||
- Check bone roll in Edit Mode
|
||||
- Verify constraint influence
|
||||
- Review mapping (especially left/right)
|
||||
- Test with simple animation first
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Problem:** "Retargeting is slow"
|
||||
|
||||
**Solutions:**
|
||||
- Close other Blender instances
|
||||
- Reduce FBX complexity (remove unnecessary bones)
|
||||
- Use SSD for faster file I/O
|
||||
- Process in batches during off-hours
|
||||
Reference in New Issue
Block a user