Hand Shape Calibration

Wuji Glove uses EMF data to solve finger-joint angles, which first requires an IK calibration to generate a URDF model matched to the wearer's hand. Calibration output belongs to the SDK user and hand side. Any glove of the same side under the same user shares it, so swapping gloves needs no recalibration.

When to Calibrate

• The first time an SDK user uses a glove on a given side
• A new wearer, calibrated under their own user

Left and right gloves calibrate independently. Under the same SDK user, switching to another glove of the same side reuses the existing calibration, no recalibration needed. With SDK user isolation on, each user keeps their own calibration URDF. See SDK User Management.

SDK User Requirement

Calibration output belongs to a named SDK user. The default user neither stores calibration output nor loads it — real-time IK always uses the built-in default model. Create and switch to a named user before calibrating:

from wuji_sdk import SdkManager

manager = SdkManager.instance()
user = manager.create_user("alice")     # "alice" is the display name
manager.switch_user(user["user_id"])    # switch by user_id, not display name

Calibrating or setting a custom URDF under the default user raises an error that tells you to run create_user and switch_user first.

Calibration Flow

Calibration asks the wearer to follow a set of guided poses while the SDK captures EMF data and solves the matching URDF.

Synchronous Blocking Call

Best for scripts and command-line tools:

from wuji_sdk import SdkManager, Handedness

manager = SdkManager.instance()
glove = manager.connect(handedness=Handedness.Left, device_name="glove")

result = glove.calibrate_blocking(timeout_s=900.0)

print("handedness:", result["handedness"])
print("calibrated urdf:", result["calibrated_urdf"])
print("poses collected:", result["poses_collected"])
print("sdk user:", result["sdk_user"]["display_name"])

calibrate_blocking() does not return until calibration finishes or times out, and Ctrl+C is deferred until the call returns.

Asynchronous Call

asyncio programs use the async API, which supports standard cancellation:

result = await glove.calibrate(timeout_s=900.0)

Parameters

Real-Time Feedback

Use the on_feedback callback to track calibration state:

def on_feedback(fb):
    if fb.get("state") == "collecting":
        progress = fb.get("progress", 0.0)
        step = fb.get("step_index", 0)
        total = fb.get("step_total", 0)
        print(f"step {step}/{total}: {progress*100:.0f}%")
    for hint in fb.get("hints", []):
        print(f"hint: {hint}")

result = glove.calibrate_blocking(on_feedback=on_feedback)

The fb dict carries the current pose index, state, progress, captured frame count, pose-deviation diagnostics (metrics), and hint text (hints).

Custom URDF Override

glove.hand_model_path().set(path) points to a user-supplied external URDF file. It's the canonical accessor for the calibration.hand_model_path resource and has the highest priority in the URDF lookup order:

# Set a custom hand URDF (highest real-time IK priority)
glove.hand_model_path().set("/path/to/custom_hand.urdf")

# Read back the current override
print(glove.hand_model_path().get())

Setting a path reloads the online-IK streams (hand_joint_angles, tip_poses, hand_skeleton) against the custom URDF. Set an empty path to fall back to the current user's calibrated model. Only paths outside the SDK-managed directory count as an external override — a path inside the managed directory has no effect.

The custom URDF override is available only to a named SDK user. Calling set() under the default user is rejected, so switch to a named user first, matching the user isolation of calibration output.

URDF Lookup Order

Priority for real-time IK and tf_static when loading the hand URDF:

1. External custom path: calibration.hand_model_path pointing to a file outside the SDK-managed directory
2. Current user's calibrated model: the stable per-side files left_hand.urdf / right_hand.urdf for that SDK user
3. Built-in default URDF: the SDK's own model per hand side

Return Fields

Summary returned by calibrate() / calibrate_blocking():

Where Calibration Is Stored

The stable files are named by SDK user and hand side. All same-side gloves under one user share the same model:

Uniqueness comes from the (user_id, hand_side) pair and no longer binds to a device serial number. Switching the SDK user reloads the matching model for connected devices automatically, no reconnect required. Writes use an atomic replace, so a failed calibration never corrupts existing output.

Calibration bundles use a new format: hand models are user-level, tactile data stays per serial number. Importing a bundle from an older SDK version keeps the tactile data but skips the old per-serial-number calibration (no longer loaded, no migration). Bundles exported by this version require an up-to-date SDK to import.

Upgrading From Older Versions

• The calibration.hand_profile and calibration.hand_model_paths.* parameters (including the hand_1 / hand_2 aliases) were removed. Setting these paths fails with PathNotFound. Values left on disk stay readable but are ignored at runtime.
• The calibration result no longer includes device_sn, hand_profile, active_hand_profile, generated_hand_profiles, or calibrated_urdfs. Use handedness and calibrated_urdf instead.

Error Handling

Resource Path Reference