### Install smplx Library

Source: https://github.com/kosukefukazawa/smpl2bvh/blob/main/README.md

Install the smplx library with all dependencies using pip. This is a prerequisite for using the smpl2bvh script.

```bash
    pip install smplx[all]
```

--------------------------------

### Run smpl2bvh Conversion Script

Source: https://github.com/kosukefukazawa/smpl2bvh/blob/main/README.md

Execute the smpl2bvh script from the command line. Specify gender, input pose file path, frames per second, output path, and optionally enable mirroring.

```python
    python smpl2bvh.py --gender MALE --poses ${PATH_TO_Y0UR_INPUT} --fps 60 --output ${PATH_TO_SAVE} --mirror
```

--------------------------------

### Mirror SMPL Motion Data

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Demonstrates how to mirror motion data by swapping joints and flipping axes. Requires SMPL joint names and parent indices to correctly identify symmetrical joints.

```python
from smpl2bvh import mirror_rot_trans
from utils import quat
import numpy as np

# SMPL joint names
names = [
    "Pelvis", "Left_hip", "Right_hip", "Spine1", "Left_knee", "Right_knee",
    "Spine2", "Left_ankle", "Right_ankle", "Spine3", "Left_foot", "Right_foot",
    "Neck", "Left_collar", "Right_collar", "Head", "Left_shoulder", "Right_shoulder",
    "Left_elbow", "Right_elbow", "Left_wrist", "Right_wrist", "Left_palm", "Right_palm"
]

# Parent indices for SMPL skeleton
parents = np.array([-1, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 9, 12, 13, 14, 16, 17, 18, 19, 20, 21])

# Original motion data
local_rotations = quat.normalize(np.random.randn(100, 24, 4))  # (frames, joints, 4)
translations = np.random.randn(100, 3)                          # (frames, 3)

# Create mirrored motion
mirrored_rotations, mirrored_translations = mirror_rot_trans(
    local_rotations, translations, names, parents
)

print(f"Original translation X: {translations[0, 0]:.3f}")
print(f"Mirrored translation X: {mirrored_translations[0, 0]:.3f}")  # Negated
```

--------------------------------

### Compute Forward Kinematics (FK)

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Computes global space rotations and positions from local joint data using the skeleton hierarchy. Requires local rotations, local positions, and a parent array defining the skeleton structure.

```python
from utils import quat
import numpy as np

# Define skeleton hierarchy (SMPL 24-joint)
parents = np.array([-1, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 9, 12, 13, 14, 16, 17, 18, 19, 20, 21])

# Local rotations (quaternions) and positions
local_rotations = quat.normalize(np.random.randn(100, 24, 4))  # (fnum, jnum, 4)
local_positions = np.random.randn(100, 24, 3) * 0.1            # (fnum, jnum, 3)

# Compute global transforms
global_rotations, global_positions = quat.fk(local_rotations, local_positions, parents)

print(f"Global rotations shape: {global_rotations.shape}")  # (100, 24, 4)
print(f"Global positions shape: {global_positions.shape}")  # (100, 24, 3)

# Rotation-only forward kinematics
global_rotations_only = quat.fk_rot(local_rotations, parents)
```

--------------------------------

### quat.fk

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Computes global space rotations and positions from local space joint rotations and positions using the skeleton hierarchy.

```APIDOC
## quat.fk

### Description
Computes global space rotations and positions from local space joint rotations and positions using the skeleton hierarchy.

### Parameters
#### Request Body
- **local_rotations** (ndarray) - Required - Local space rotations (quaternions).
- **local_positions** (ndarray) - Required - Local space positions.
- **parents** (ndarray) - Required - Skeleton hierarchy indices.
```

--------------------------------

### quat.ik

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Computes local space rotations and positions from global space transforms.

```APIDOC
## quat.ik

### Description
Computes local space rotations and positions from global space transforms. Useful for converting between coordinate systems.

### Parameters
#### Request Body
- **global_rotations** (ndarray) - Required - Global space rotations.
- **global_positions** (ndarray) - Required - Global space positions.
- **parents** (ndarray) - Required - Skeleton hierarchy indices.
```

--------------------------------

### Convert SMPL poses to BVH using smpl2bvh

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Use the smpl2bvh function to convert SMPL pose data from PKL or NPZ files to BVH format. Specify model paths, gender, input pose file, frame rate, and output file. Optionally generate mirrored motion.

```python
python smpl2bvh.py --model_path data/smpl/ \
                   --gender MALE \
                   --poses data/dance_motion.pkl \
                   --fps 60 \
                   --output output/dance.bvh \
                   --mirror
```

```python
from smpl2bvh import smpl2bvh

smpl2bvh(
    model_path="data/smpl/",
    model_type="smpl",
    gender="MALE",
    poses="data/gWA_sFM_cAll_d27_mWA5_ch20.pkl",  # AIST++ format
    fps=60,
    output="output/dance_motion.bvh",
    mirror=True  # Also generate mirrored motion
)
```

```python
smpl2bvh(
    model_path="data/smpl/",
    model_type="smpl",
    gender="FEMALE",
    poses="data/amass_motion.npz",
    fps=30,
    output="output/walking.bvh",
    mirror=False
)
```

--------------------------------

### Compute Inverse Kinematics (IK)

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Computes local space rotations and positions from global space transforms. This is useful for converting between coordinate systems or when target global poses are known. Requires global rotations, global positions, and a parent array.

```python
from utils import quat
import numpy as np

# Define skeleton hierarchy
parents = np.array([-1, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 9, 12, 13, 14, 16, 17, 18, 19, 20, 21])

# Global rotations and positions
global_rotations = quat.normalize(np.random.randn(100, 24, 4))
global_positions = np.random.randn(100, 24, 3)

# Compute local transforms
local_rotations, local_positions = quat.ik(global_rotations, global_positions, parents)

print(f"Local rotations shape: {local_rotations.shape}")  # (100, 24, 4)
print(f"Local positions shape: {local_positions.shape}")  # (100, 24, 3)

# Rotation-only inverse kinematics
local_rotations_only = quat.ik_rot(global_rotations, parents)
```

--------------------------------

### bvh.load

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Loads and parses a BVH animation file, extracting the joint hierarchy, rotations, positions, and timing information into a structured dictionary format.

```APIDOC
## bvh.load

### Description
Parses a BVH file into a dictionary containing joint hierarchy and animation data.

### Parameters
- **file_path** (string) - Required - Path to the .bvh file.

### Response
- **names** (list) - List of joint names.
- **parents** (list) - List of parent joint indices.
- **offsets** (ndarray) - Joint rest pose offsets.
- **rotations** (ndarray) - Rotation data per frame.
- **positions** (ndarray) - Position data per frame.
- **order** (string) - Rotation order.
- **frametime** (float) - Frame duration.
```

--------------------------------

### Convert axis-angle to quaternions using quat.from_axis_angle

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Convert axis-angle rotation representations to quaternions using the quat.from_axis_angle function. This is a core conversion used in processing SMPL pose parameters, transforming vectors of shape (N, 24, 3) into quaternions of shape (N, 24, 4).

```python
from utils import quat
import numpy as np

# Convert SMPL axis-angle rotations to quaternions
# SMPL stores rotations as axis-angle vectors (N, 24, 3)
axis_angle_rotations = np.random.randn(100, 24, 3)  # 100 frames, 24 joints

# Convert to quaternions (N, 24, 4)
quaternions = quat.from_axis_angle(axis_angle_rotations)
print(f"Quaternion shape: {quaternions.shape}")  # (100, 24, 4)

# Each quaternion is [w, x, y, z] format
print(f"First joint quaternion: {quaternions[0, 0]}")  # [w, x, y, z]
```

--------------------------------

### Load BVH animation file using bvh.load

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Use bvh.load to parse a BVH file and extract animation data including joint names, hierarchy, offsets, rotations, positions, rotation order, and frame time. This function is useful for analyzing existing BVH files.

```python
from utils import bvh

# Load a BVH file
data = bvh.load("animation.bvh")

# Access the parsed data
print(f"Joint names: {data['names']}")        # ['Pelvis', 'Left_hip', 'Right_hip', ...]
print(f"Parent indices: {data['parents']}")   # [-1, 0, 0, 0, 1, 2, ...]
print(f"Joint offsets: {data['offsets'].shape}")      # (24, 3)
print(f"Rotations: {data['rotations'].shape}")        # (num_frames, 24, 3)
print(f"Positions: {data['positions'].shape}")        # (num_frames, 24, 3)
print(f"Rotation order: {data['order']}")             # 'zyx'
print(f"Frame time: {data['frametime']}")             # 0.0166667 (60 fps)

# Calculate duration
num_frames = len(data['rotations'])
duration = num_frames * data['frametime']
print(f"Animation duration: {duration:.2f} seconds")
```

--------------------------------

### quat.from_axis_angle

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Converts axis-angle rotation representation to quaternions, used for processing SMPL pose parameters.

```APIDOC
## quat.from_axis_angle

### Description
Converts axis-angle rotation vectors to quaternions.

### Parameters
- **axis_angle_rotations** (ndarray) - Required - Axis-angle rotation vectors (N, 24, 3).
```

--------------------------------

### quat.to_euler

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Converts quaternions to Euler angles with a specified rotation order, essential for BVH output.

```APIDOC
## quat.to_euler

### Description
Converts quaternions to Euler angles with specified rotation order. Essential for BVH output which uses Euler angle representation.

### Parameters
#### Request Body
- **quaternions** (ndarray) - Required - Input quaternions to convert.
- **order** (string) - Required - Rotation order (e.g., 'zyx', 'yzx', 'zxy', 'yxz').

### Response
- **euler_radians** (ndarray) - Euler angles in radians.
```

--------------------------------

### bvh.save

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Writes animation data to a BVH file with proper hierarchy structure, motion channels, and frame data formatting.

```APIDOC
## bvh.save

### Description
Saves animation data to a BVH file.

### Parameters
- **file_path** (string) - Required - Output path for the BVH file.
- **bvh_data** (dict) - Required - Dictionary containing rotations, positions, offsets, parents, names, order, and frametime.
- **save_positions** (boolean) - Optional - Whether to save all joint positions.
```

--------------------------------

### quat.mul

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Multiplies two quaternions to combine rotations, used for composing rotations in the kinematic chain.

```APIDOC
## quat.mul

### Description
Multiplies two quaternions to combine rotations. Used for composing rotations in the kinematic chain.

### Parameters
#### Request Body
- **rot_a** (ndarray) - Required - First rotation quaternion.
- **rot_b** (ndarray) - Required - Second rotation quaternion.
```

--------------------------------

### smpl2bvh

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

The primary function that converts SMPL pose parameters to BVH format. It loads the SMPL model, processes pose data from NPZ or PKL files, and generates a properly formatted BVH file.

```APIDOC
## smpl2bvh

### Description
Converts SMPL pose parameters to BVH format.

### Parameters
- **model_path** (string) - Required - Path to the SMPL model directory.
- **model_type** (string) - Required - Type of model (e.g., 'smpl').
- **gender** (string) - Required - Gender of the model (e.g., 'MALE', 'FEMALE').
- **poses** (string) - Required - Path to the pose data file (NPZ or PKL).
- **fps** (int) - Required - Frame rate for the output BVH file.
- **output** (string) - Required - Output file path for the generated BVH.
- **mirror** (boolean) - Optional - Whether to generate a mirrored version of the motion.
```

--------------------------------

### Convert Quaternions to Euler Angles

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Converts quaternions to Euler angles. The default order 'zyx' is suitable for BVH output. Supports various rotation orders and conversion to degrees.

```python
from utils import quat
import numpy as np

# Convert quaternions to Euler angles (in radians)
quaternions = np.random.randn(100, 24, 4)
quaternions = quat.normalize(quaternions)

# Convert to ZYX Euler angles (default for BVH)
euler_radians = quat.to_euler(quaternions, order='zyx')
print(f"Euler shape: {euler_radians.shape}")  # (100, 24, 3)

# Convert to degrees for BVH
euler_degrees = np.degrees(euler_radians)

# Supported orders: 'zyx', 'yzx', 'zxy', 'yxz'
euler_yzx = quat.to_euler(quaternions, order='yzx')
```

--------------------------------

### Spherical Linear Interpolation (SLERP) of Quaternions

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Performs spherical linear interpolation between two quaternions. This function is ideal for creating smooth transitions between rotation keyframes in animations.

```python
from utils import quat
import numpy as np

# Two rotation keyframes
rot_start = quat.from_euler(np.array([0.0, 0.0, 0.0]), order='zyx')
rot_end = quat.from_euler(np.array([0.0, np.pi/2, 0.0]), order='zyx')

# Interpolate at various points
t_values = [0.0, 0.25, 0.5, 0.75, 1.0]
for t in t_values:
    interpolated = quat.slerp(rot_start, rot_end, t)
    euler = np.degrees(quat.to_euler(interpolated[None], order='zyx'))
    print(f"t={t}: rotation Y = {euler[0, 1]:.1f} degrees")

# Output:
# t=0.0: rotation Y = 0.0 degrees
# t=0.25: rotation Y = 22.5 degrees
# t=0.5: rotation Y = 45.0 degrees
# t=0.75: rotation Y = 67.5 degrees
# t=1.0: rotation Y = 90.0 degrees
```

--------------------------------

### Save animation data to BVH file using bvh.save

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Use bvh.save to write animation data to a BVH file. The function requires a dictionary containing rotations, positions, offsets, parents, names, rotation order, and frame time. An optional argument `save_positions` can be set to True.

```python
from utils import bvh
import numpy as np

# Prepare BVH data structure
bvh_data = {
    "rotations": rotations,       # np.ndarray (fnum, jnum, 3) - Euler angles in degrees
    "positions": positions,       # np.ndarray (fnum, jnum, 3) - Joint positions
    "offsets": offsets,           # np.ndarray (jnum, 3) - Rest pose offsets
    "parents": parents,           # np.ndarray (jnum,) - Parent joint indices
    "names": [
        "Pelvis", "Left_hip", "Right_hip", "Spine1",
        "Left_knee", "Right_knee", "Spine2", "Left_ankle",
        "Right_ankle", "Spine3", "Left_foot", "Right_foot",
        "Neck", "Left_collar", "Right_collar", "Head",
        "Left_shoulder", "Right_shoulder", "Left_elbow",
        "Right_elbow", "Left_wrist", "Right_wrist",
        "Left_palm", "Right_palm"
    ],
    "order": "zyx",               # Rotation order
    "frametime": 1 / 60,          # Frame duration (60 fps)
}

# Save to BVH file
bvh.save("output_animation.bvh", bvh_data)

# Save with all joint positions (not recommended for most cases)
bvh.save("output_animation.bvh", bvh_data, save_positions=True)
```

--------------------------------

### quat.slerp

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Performs spherical linear interpolation between quaternions for smooth rotation blending.

```APIDOC
## quat.slerp

### Description
Spherical linear interpolation between quaternions. Produces smooth rotation blending between keyframes.

### Parameters
#### Request Body
- **rot_start** (ndarray) - Required - Starting rotation.
- **rot_end** (ndarray) - Required - Ending rotation.
- **t** (float) - Required - Interpolation factor between 0.0 and 1.0.
```

--------------------------------

### quat.mul_vec

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Rotates 3D vectors by quaternions.

```APIDOC
## quat.mul_vec

### Description
Rotates 3D vectors by quaternions. Used to transform positions through the skeleton hierarchy.

### Parameters
#### Request Body
- **rotation** (ndarray) - Required - Rotation quaternion.
- **vectors** (ndarray) - Required - 3D vectors to rotate.
```

--------------------------------

### Multiply Quaternions to Combine Rotations

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Multiplies two quaternions to combine rotations. This function works with both single quaternions and batched arrays, useful for composing sequential rotations in a kinematic chain.

```python
from utils import quat
import numpy as np

# Create two rotations
rot_a = quat.from_euler(np.array([0.1, 0.2, 0.3]), order='zyx')
rot_b = quat.from_euler(np.array([0.0, 0.5, 0.0]), order='zyx')

# Combine rotations: apply rot_a then rot_b
combined = quat.mul(rot_a, rot_b)

# Works with batched quaternions
batch_rot_a = np.random.randn(100, 24, 4)
batch_rot_b = np.random.randn(100, 24, 4)
batch_rot_a = quat.normalize(batch_rot_a)
batch_rot_b = quat.normalize(batch_rot_b)

batch_combined = quat.mul(batch_rot_a, batch_rot_b)
print(f"Combined shape: {batch_combined.shape}")  # (100, 24, 4)
```

--------------------------------

### Rotate 3D Vectors by Quaternions

Source: https://context7.com/kosukefukazawa/smpl2bvh/llms.txt

Rotates 3D vectors using quaternion multiplication. This is commonly used to transform positions or directions through a skeleton's hierarchy.

```python
from utils import quat
import numpy as np

# Create a rotation quaternion (90 degrees around Y axis)
rotation = quat.from_euler(np.array([[0.0, np.pi/2, 0.0]]), order='zyx')

# Vector to rotate
vectors = np.array([[1.0, 0.0, 0.0]])  # X-axis unit vector

# Apply rotation
rotated = quat.mul_vec(rotation, vectors)
print(f"Original: {vectors[0]}")      # [1, 0, 0]
print(f"Rotated: {rotated[0]}")       # [0, 0, -1] (approximately)

# Batch rotation of multiple vectors
batch_rotations = quat.normalize(np.random.randn(100, 24, 4))
batch_vectors = np.random.randn(100, 24, 3)
rotated_batch = quat.mul_vec(batch_rotations, batch_vectors)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.