Retarget Parameters

Required Parameters

Input Files

You can pass file paths (auto-uploaded), Asset objects, or asset IDs for both inputs:

Tracker (C3D file)

Option 1: File path (Recommended)
The SDK uploads the file automatically.

result = client.retarget(
    tracker="path/to/motion.c3d",
    markerset="path/to/markerset.xml",
)

Option 2: Asset object or asset ID

tracker_asset = client.assets.upload("motion.c3d")
result = client.retarget(
    tracker=tracker_asset,
    markerset="path/to/markerset.xml",
)

# Or use asset ID
result = client.retarget(
    tracker="asset-uuid-here",
    markerset="markerset-asset-uuid",
)

Requirements:

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

Markerset (XML file)

Requirements:

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

Optional Parameters

Character

character

Character preset or ID to retarget onto.

Default: Character.MYOSKELETON_V2

Example:

from myosdk.types import Character

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    character=Character.MYOSKELETON_V2,
)

character_version

Character version to use.

Default: "v1.0.0" (or from character preset)

Output

export_glb

Export motion as a GLB file in addition to qpos, xpos, and model.

Default: False

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    export_glb=True,
)
result.download_motion("out/motion.glb")

rotation

Optional rotation applied to mocap coordinates before retargeting.

Type: "yup_to_zup" | "ydown_to_zup" | None

Default: None (no rotation applied)

Use this when your input coordinate system is:

• OpenSim style (Y-up) → use "yup_to_zup" to convert to MuJoCo's Z-up
• OpenCV style (Y-down) → use "ydown_to_zup" to convert to MuJoCo's Z-up

If you're unsure of your source convention or already work in MuJoCo's frame, leave this unset.

Scaling Parameters

enable_scaling

Whether to enable body scaling during retargeting.

Default: True

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    enable_scaling=True,
)

When to disable:

• You want to preserve the original motion scale exactly
• You're working with normalized motion data

subject_gender

Subject gender for anthropometric scaling.

Default: "male"

Type: "male" | "female"

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    subject_gender="female",
)

subject_height

Subject height in meters for anthropometric scaling.

Default: None (estimated from motion data)

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    subject_height=1.75,  # 175 cm
)

subject_weight

Subject weight in kilograms for anthropometric scaling.

Default: None (estimated from motion data)

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    subject_weight=70.0,
)

Streaming and Control

stream_status

Stream status updates during execution (when using blocking calls).

Default: False

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    stream_status=True,
)

on_status

Callback function called for each status event when stream_status=True.

Default: Prints status to stdout when stream_status=True

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    stream_status=True,
    on_status=lambda e: print(f"Status: {e.status}"),
)

output_dir

Directory to download outputs to when the job completes (blocking calls only).

Default: None

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    output_dir="out/",
)
# Outputs are already in out/

timeout

Maximum seconds to wait for job completion (blocking calls only).

Default: 300

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    timeout=600,  # 10 minutes
)

Metadata

metadata

Optional metadata dictionary for tracking and organization.

Default: None

Example:

result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    metadata={
        "project": "game_animation",
        "scene": "walking_sequence",
        "subject": "actor_001",
    },
)

Complete Example

import os
from myosdk import Client
from myosdk.types import Character

client = Client(api_key=os.getenv("MYO_API_KEY"))

# Simple one-call retarget (file paths auto-upload)
result = client.retarget(
    tracker="motion.c3d",
    markerset="markerset.xml",
    character=Character.MYOSKELETON_V2,
    export_glb=True,
    enable_scaling=True,
    subject_gender="male",
    subject_height=1.75,
    subject_weight=70.0,
    stream_status=True,
    output_dir="out/",
    timeout=600,
    metadata={"project": "animation_pipeline", "subject": "actor_001"},
)

# Or download manually
result.download_all("out/")

Best Practices

1. Use file paths when possible – Let the SDK handle uploads and asset IDs.
2. Provide subject measurements – Improves accuracy when you have the data.
3. Use metadata – Helps organize and track your jobs.
4. Set a reasonable timeout – Long clips may need timeout=600 or more.

Troubleshooting

"Asset purpose mismatch" error

• Ensure C3D and markerset assets have purpose "retarget" (auto when uploading .c3d / .xml).
• Verify assets are completed before using asset IDs.

"Invalid subject parameters" error

• Check that subject_gender is exactly "male" or "female".
• Ensure subject_height and subject_weight are positive numbers.
• Verify units (meters for height, kilograms for weight).

"Motion output is not available" error

• Set export_glb=True when creating the retarget job if you need the motion (.glb) file.

Next Steps

• SDK Reference - Complete SDK documentation
• Retargeting Tutorial - Complete workflow example
• File Formats - Input and output format details