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. The SDK ships a Python calibration API, runtime hand-profile switching, user-supplied URDF override, and per-user / per-device-serial-number isolation of calibration files.

When to Calibrate

• First time you use a glove
• A different wearer puts it on
• The application needs to switch between the Wuji Hand and Wuji Hand 2 models

The device serial number already encodes which side (left or right) the glove belongs to, so the left and right gloves are calibrated independently and never share URDFs. When SDK user isolation is enabled, each user keeps a separate calibration URDF. See SDK User Management for user management.

Calibration Flow

Calibration asks the wearer to follow a sequence of poses while the SDK collects EMF data and solves a matching URDF.

Synchronous Blocking Call

Best for scripts and CLI 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("device_sn:", result["device_sn"])
print("active hand profile:", result["active_hand_profile"])
print("generated profiles:", result["generated_hand_profiles"])
print("URDFs:", result["calibrated_urdfs"])
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. Ctrl+C is deferred until the call returns.

Asynchronous Call

Use the async API in asyncio programs. It honors standard asyncio cancellation:

result = await glove.calibrate(timeout_s=900.0)

Parameters

Real-time Feedback

Pass an on_feedback callback to receive per-step status:

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)

fb carries the current pose index, state, progress, frame count, pose-deviation diagnostic metrics (metrics), and human-readable hints (hints).

Hand Profile Selection

Wuji Glove ships two real-time IK models:

Pin a Hand Profile at Calibration Time

from wuji_sdk import WujiHandProfile

result = glove.calibrate_blocking(
    hand_profile=WujiHandProfile.WUJI_HAND_2,
)
# result["generated_hand_profiles"] == ["wujihand2"]
# result["calibrated_urdfs"] == {"wujihand2": "/path/to/...urdf"}

When you omit hand_profile, the SDK uses the same captured data to generate URDFs for both profiles and writes them to:

• calibration.hand_model_paths.wujihand
• calibration.hand_model_paths.wujihand2

Real-time IK defaults to "wujihand" and can switch at runtime.

Switch Hand Profile at Runtime

Set calibration.hand_profile to swap the real-time IK model:

# Switch to Wuji Hand 2
glove.set("calibration.hand_profile", "wujihand2")

# Switch back to Wuji Hand
glove.set("calibration.hand_profile", "wujihand")

The switch takes effect on the next frame. When calibration.hand_profile is unset, the SDK defaults to "wujihand".

Custom URDF Override

calibration.hand_model_path lets you point real-time IK at a user-supplied URDF. It has the highest priority:

glove.set("calibration.hand_model_path", "/path/to/custom_hand.urdf")

Clear the value to fall back to the calibration-generated URDF for the current calibration.hand_profile.

URDF Lookup Order

Real-time IK, tf_static, and offline_pipeline resolve the hand URDF in this order:

1. User-supplied path: calibration.hand_model_path pointing to a file outside the SDK-managed directory
2. Calibrated URDF for the active profile: calibration.hand_model_paths.<profile> (wujihand or wujihand2)
3. Legacy compatibility path: calibration.hand_model_paths.hand_1/hand_2 or calibration.hand_model_path written by older SDK versions
4. Built-in default URDF: shipped with the SDK, selected by hand side

Return Fields

Summary returned by calibrate() / calibrate_blocking():

Calibration Artifacts

Generated URDF files are named <sn>_hand_<profile>_<calibration_id>.urdf. The root directory is scoped by SDK user:

Uniqueness is guaranteed by the (user_id, device_sn, hand_profile) tuple. Switching the SDK user reloads the matching URDF for connected devices automatically, no reconnect required.

Error Handling

Resource Reference