Retarget Parameters

Required Parameters

Input Files

You must provide either asset IDs or direct S3 keys for both input files:

C3D File

Option 1: Asset ID (Recommended)

job = client.jobs.start_retarget(
    c3d_asset_id="uuid",
    markerset_asset_id="uuid"
)

Option 2: Direct S3 Key

job = client.jobs.start_retarget(
    c3d_s3="s3://bucket/path/to/file.c3d",
    markerset_s3="s3://bucket/path/to/markerset.xml"
)

Requirements:

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

Markerset XML

Requirements:

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

Optional Parameters

Checking available versions:

character = client.characters.get(character_id)
for version in character["ready_versions"]:
    print(f"Version {version['version']}: {version['status']}")

Scaling Parameters

enable_scaling

Whether to enable body scaling during retargeting.

Default: True

Type: bool

Example:

# Enable scaling (default)
job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    enable_scaling=True
)

# Disable scaling
job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    enable_scaling=False
)

When to disable:

• You want to preserve the original motion scale exactly
• You're working with normalized motion data
• You need consistent scaling across multiple retargets

subject_gender

Subject gender for anthropometric scaling.

Default: "male"

Type: Literal["male", "female"]

Example:

job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    subject_gender="female"
)

Impact:

• Affects anthropometric scaling calculations
• Uses gender-specific body proportions
• Improves accuracy for subject-specific retargeting

subject_height

Subject height in meters for anthropometric scaling.

Default: None (estimated from motion data)

Type: float | None

Example:

job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    subject_height=1.75  # 175 cm
)

When to specify:

• You know the exact subject height
• You want more accurate anthropometric scaling
• Working with subjects of non-average height

Note: If not provided, height is estimated from the motion data.

subject_weight

Subject weight in kilograms for anthropometric scaling.

Default: None (estimated from motion data)

Type: float | None

Example:

job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    subject_weight=70.0  # 70 kg
)

When to specify:

• You know the exact subject weight
• You want more accurate anthropometric scaling
• Working with subjects of non-average weight

Note: If not provided, weight is estimated from the motion data.

Metadata

metadata

Optional metadata dictionary for tracking and organization.

Default: None

Type: dict[str, Any] | None

Example:

job = client.jobs.start_retarget(
    c3d_asset_id=c3d_id,
    markerset_asset_id=markerset_id,
    metadata={
        "project": "game_animation",
        "scene": "walking_sequence",
        "subject": "actor_001",
        "notes": "First take"
    }
)

Use cases:

• Track project information
• Organize jobs by scene or subject
• Add notes or tags
• Link to external systems

Note: Metadata is stored with the job and can be retrieved later via client.jobs.get(job_id).

Complete Example

import os
from myosdk import Client

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

# Upload input files
c3d_asset = client.assets.upload_file("motion.c3d")
markerset_asset = client.assets.upload_file("markerset.xml")

# Start retarget job with all parameters
job = client.jobs.start_retarget(
    c3d_asset_id=c3d_asset["asset_id"],
    markerset_asset_id=markerset_asset["asset_id"],
    enable_scaling=True,
    subject_gender="male",
    subject_height=1.75,
    subject_weight=70.0,
    metadata={
        "project": "animation_pipeline",
        "subject": "actor_001"
    }
)

# Wait for completion
result = client.jobs.wait(job["job_id"])

# Download result
output_asset_id = result["output"]["retarget_output_asset_id"]
client.assets.download(output_asset_id, "output.npz")

Best Practices

1. Always use asset IDs - More reliable than direct S3 keys
2. Provide subject measurements - Improves accuracy when you have the data
3. Use metadata - Helps organize and track your jobs
4. Validate characters - Check that character versions are READY before using them

Troubleshooting

"Asset purpose mismatch" error

• Ensure C3D and markerset assets have purpose "retarget"
• Verify assets are in "completed" status
• Re-upload files if needed

"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)

Next Steps

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