Hand Model Calibration

SDK Reference

Wuji Glove uses EMF data to solve finger-joint angles, which first requires a hand model 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

• Python

• C

Python: See the Python API examples earlier on this page.

The C API matches the Python API on this page and uses the wuji_glove_ prefix. For initialization conventions, memory management, error codes, and build setup, see the C API Reference.

Custom Hand Model for Online IK

wuji_glove_set_hand_model_path sets a custom hand URDF path and wuji_glove_get_hand_model_path reads it back, mirroring Python glove.hand_model_path().set(path) / .get(). Setting a path reloads the online-IK streams (hand_joint_angles, tip_poses, hand_skeleton) against the custom URDF through the SDK’s calibration-generation mechanism. The getter uses the two-call size query — pass NULL to get the required length, then call again to fill:

// Set a custom hand URDF for online IK
wuji_glove_set_hand_model_path(dev, "/path/to/hand.urdf");

// Read it back (two-call size query)
size_t needed = 0;
wuji_glove_get_hand_model_path(dev, NULL, 0, &needed);
char *path = malloc(needed);
wuji_glove_get_hand_model_path(dev, path, needed, NULL);
printf("hand model: %s\n", path);
free(path);

Only a named SDK user can set a custom hand model: online IK under the default SDK user always uses the built-in default URDF, so calling wuji_glove_set_hand_model_path there fails and wuji_last_error tells you to switch to a named user first. An unreadable path also fails immediately and is never stored.

Hand Model Calibration

Wuji Glove hand model calibration offers both synchronous and asynchronous entry points in C, matching Python glove.calibrate(). Calibration is per-user, so switch to a named SDK user first — the default user fails calibration outright.

Get default options with wuji_glove_calibration_options_default (skip_constraints to skip constraint checks, timeout_s for the timeout in seconds). The feedback callback receives a WujiGloveCalibrationFeedback with the current pose progress. Only state and progress are always present. Every other scalar field is guarded by a companion has_* flag — read step_index only when has_step_index is true, and the same for step_total, step_name, hold_elapsed, frames_collected, and the rest. metrics and hints are arrays with no has_* flag: check metrics_len / hints_len instead. Each WujiGloveCalibrationMetric carries its own guards: a metric has finger / finger_b only when has_finger / has_finger_b is true, so metrics aren’t necessarily per-finger.

For an async session, start begins calibration, then poll with try_finish or block with wait until it finishes, cancel requests cooperative cancellation, and session_free releases the handle:

void on_feedback(const WujiGloveCalibrationFeedback* fb, void* user) {
    // fb->state / fb->progress / fb->step_index / fb->metrics ...
    // fb is valid only during the callback; copy any fields you need to keep
}

WujiGloveCalibrationOptions options;
wuji_glove_calibration_options_default(&options);

WujiGloveCalibrationSession* session = NULL;
WujiStatus st = wuji_glove_calibration_start(dev, &options, on_feedback, /*user_data=*/NULL, &session);

WujiGloveCalibrationResult result = {0};
bool done = false;
while (st == WUJI_STATUS_OK && !done) {
    if (/* Ctrl+C received */) wuji_glove_calibration_cancel(session);
    st = wuji_glove_calibration_try_finish(session, &done, &result);
    if (st != WUJI_STATUS_OK || done) break;
    nanosleep(&(struct timespec){ .tv_nsec = 50 * 1000 * 1000 }, NULL);   // poll interval ~50 ms
}
if (session) wuji_glove_calibration_session_free(session);

// Read the result only when start succeeded and calibration finished cleanly; don't touch result fields on cancel or failure
if (st == WUJI_STATUS_OK && done) {
    printf("side=%s poses=%u urdf=%s user=%s\n",
           handedness_name(result.handedness), result.poses_collected,
           result.calibrated_urdf, result.sdk_user.display_name);
    wuji_glove_calibration_result_free(&result);
}

The synchronous entry point wuji_glove_calibrate blocks in a single call until calibration finishes, takes the same parameters, and writes straight into a WujiGloveCalibrationResult:

WujiGloveCalibrationResult result = {0};
wuji_glove_calibrate(dev, &options, on_feedback, /*user_data=*/NULL, &result);
wuji_glove_calibration_result_free(&result);

WujiGloveCalibrationResult carries the pose count poses_collected, per-pose frame counts frames_per_pose, handedness handedness, the generated URDF path calibrated_urdf, and the owning user snapshot sdk_user. Treat calibrated_urdf as an opaque SDK-allocated local path and don’t depend on its parent-directory layout. Free the result with wuji_glove_calibration_result_free when you’re done.

Cancellation is cooperative. wuji_glove_calibration_cancel returning WUJI_STATUS_OK only means the request was recorded — it doesn’t mean calibration stopped. The run maps to WUJI_STATUS_ERR_CANCELLED only when the cancellation lands before results are published. Once the run reaches the publishing stage, it can still finish successfully or fail with a publishing error, so always check the status the session actually returns rather than assuming a cancelled run yields ERR_CANCELLED. A device that doesn’t support calibration maps to WUJI_STATUS_ERR_UNSUPPORTED.