File Formats

Asset Purposes

Assets are categorized by their purpose, which determines how they're used in the platform:

retarget

Input files for retargeting jobs.

Supported formats:

• .c3d - C3D motion capture format
• .xml - XML markerset configuration

Use case: Upload C3D motion capture files and markerset XML files for retargeting.

Input Files

C3D Files

C3D (Coordinate 3D) is a standard format for motion capture data. C3D files contain 3D marker positions, analog data, and metadata.

Requirements:

• Valid C3D format
• Contains 3D marker trajectories
• Compatible with the markerset configuration

Upload:

c3d_asset = client.assets.upload_file("motion.c3d")
# Purpose is auto-detected as "retarget" from .c3d extension

Markerset XML Files

Markerset XML files define the marker configuration and skeleton structure for your C3D data.

Requirements:

• Valid XML format
• Contains marker definitions
• Matches the markers in your C3D file

Upload:

markerset_asset = client.assets.upload_file("markerset.xml")
# Purpose is auto-detected as "retarget" from .xml extension

Output Files

Retarget Output (.npz)

Retarget jobs produce .npz files (NumPy compressed archive) containing:

• Joint angles - Standardized joint angle data
• Joint names - Array of joint names corresponding to the angles
• Metadata - Additional information about the retargeting

Structure:

import numpy as np

data = np.load("output.npz")
joint_angles = data["joint_angles"]  # Shape: (frames, joints, 3) or (frames, joints)
joint_names = data["joint_names"]    # Array of joint name strings
metadata = data.get("metadata", {})   # Optional metadata dict

Download:

# After job completes
result = client.jobs.wait(job_id)
output_asset_id = result["output"]["retarget_output_asset_id"]
client.assets.download(output_asset_id, "output.npz")

Usage:

import numpy as np

# Load the output
data = np.load("output.npz")
joint_angles = data["joint_angles"]
joint_names = data["joint_names"]

print(f"Frames: {joint_angles.shape[0]}")
print(f"Joints: {joint_angles.shape[1]}")
print(f"Joint names: {joint_names}")

# Use joint angles in your application
for frame_idx in range(joint_angles.shape[0]):
    frame_angles = joint_angles[frame_idx]
    # Process frame...

Content Types

The SDK automatically detects content types from file extensions. You can also specify them explicitly:

# Auto-detected
asset = client.assets.upload_file("motion.c3d")  # content_type: "application/octet-stream"

# Explicit purpose (usually auto-detected)
asset = client.assets.upload_file(
    "motion.c3d",
    purpose="retarget",
    content_type="application/octet-stream"
)

Common content types:

• application/octet-stream - Binary files (C3D)
• application/xml - XML files
• text/xml - XML files

File Size Limits

File size limits depend on your plan:

• Default limit: 50 MB per file (for new tenants)
• Free tier: Check your plan limits at dev.myolab.ai
• Paid tiers: Higher limits available (configurable per tenant)

If you encounter size limit errors:

1. Check your plan's limits
2. Consider compressing files if possible
3. Contact support@myolab.ai for assistance

Upload Process

Upload files using the convenience method:

# Automatically handles the upload process
asset = client.assets.upload_file("motion.c3d")

Best Practices

1. Use appropriate purpose - Let the SDK auto-detect, or specify explicitly
2. Validate file formats - Ensure C3D and XML files are valid before uploading
3. Check file sizes - Be aware of your plan's limits
4. Verify uploads - Check asset status before using in jobs

Troubleshooting

"Invalid file format" error

• Verify your C3D file is valid and not corrupted
• Check that the markerset XML matches your C3D file
• Ensure file extensions are correct (.c3d, .xml)

"File too large" error

• Check your plan's file size limits
• Consider compressing files if possible

"Asset purpose mismatch" error

• Ensure you're using the correct purpose for the file type
• C3D and XML files should use "retarget" purpose

Next Steps

• SDK Reference - Complete SDK documentation
• Retargeting Tutorial - Complete workflow example
• Error Handling - Exception types and handling