Willow 5: Virtual Enrollment

Target Audience: Data Scientists, Game Developers, Research Labs
Objective: Create action reference models directly from raw 3D coordinate data or animation files.

1. Overview

Virtual Enrollment allows users to bypass AI video extraction and inject 3D skeletal data directly into the Willow 5 Engine. This method is ideal for using "mathematically perfect" data from animations (Unity/Maya/Blender), cleaned motion capture (OptiTrack/Vicon), or refined research datasets. By selecting the "Synthetic Data (Pre-Scaled)" calibration strategy in the UI, the engine natively accepts your data as ground truth.

2. Supported File Formats

FBX (.fbx) [NEW]

The standard for professional animation and game engines.

  • Requirement: The FBX should contain a skeletal animation (armature).
  • Process: The MoGen Engine runs a headless FK (Forward Kinematics) solver to resolve bone rotations into world-space coordinates.
  • Topology: The system automatically maps standard rig naming conventions to the Willow Topology. Ensure your rig contains the four normalization anchors (Shoulders 11, 12 and Hips 23, 24).

 

JSON (.json)

The primary format for web integration and custom scripting.

  • Shape: [Frames, 75, 4] (Universal) or [Frames, 76, 4] (Physics). The 4th index is Presence/Visibility.
  • Root Element: An array of frames, or a dictionary with a "data" key.
  • Standard: Values should be floating-point numbers.

 

Numpy (.npy)

Binary format for high-speed Python research workflows.

  • Shape: (N, 75, 4) or (N, 76, 4)
  • Type: float32

 

3. Data Integrity Requirements

Willow 5 uses a Relational Distance Matrix (RDM) that adapts based on your selected Spatial Engine Mode. You must adhere to the following strict data contracts depending on your target pipeline:

Spatial Unit Contracts

  • Universal Models (Scale-Invariant): You do not need to convert units (meters, inches, or generic unit-space are all acceptable). The engine mathematically normalizes all input distances against the Torso Length, dynamically making the data scale-invariant.
  • Physics Models (Metric Space): You MUST export your data in absolute Meters. Normalization is bypassed entirely. If your FBX or JSON is exported in centimeters, the DTW engine will perceive the subject as moving 100 times farther than intended, resulting in a total failure during Edge SDK Physical Inference.

 

Topology and Auto-Padding

  • Node 76 (Object Tracking): If you are building a Physics model with human-object interaction, map the object's metric XYZ centroid to Index 75 (making the array 76 points long).
  • Auto-Padding Failsafe: If you upload a legacy 75-point sequence while Physics Mode is enabled, the Cloud Oracle will safely auto-pad the 76th node with [0.0, 0.0, 0.0, 0.0] to prevent array indexing crashes.
  • Presence/Visibility (The 4th Dimension): For synthetic data, you must provide a 4th dimension for every coordinate. Set this to 1.0 for valid data. Set it to 0.0 for missing or intentionally occluded joints to ensure they are masked out of the RDM calculation.
  1. The 75-Point Topology: You MUST map your skeletal data to the Willow 75-Point Topology Map.
  2. The 4th Dimension (Presence): Willow 5 expects an [X, Y, Z, Presence] format.
    1. Set Presence to 1.0 for joints with valid data.
    2. Set Presence to 0.0 for missing or untracked joints.
  3. Indices 17-22 (The Deadzone): These are the Legacy Hand Proxies. You must always pass [0.0, 0.0, 0.0, 0.0] for these indices to prevent interference with the high-fidelity hand system.
  4. Zero-Padding: If your data source does not include hands or feet, pad indices 33-74 with [0.0, 0.0, 0.0, 0.0]. The engine will automatically skip these indices based on the model’s zone mask.

 

4. How to Import

  1. Open the SDK / Web Interface: Navigate to the Seed Learning (Enrollment) tab.
  2. Add Action Name: Enter a unique name for the model (e.g., "Elite_Backhand_01").
  3. Configure Zones: Select the kinematic zones that matter for this action (e.g., if you are importing a hand-only gesture, check only "Hands").
  4. Upload: Drag and drop your .fbx, .json, or .npy file into the upload box.
  5. Validation: The UI will label the file as "Virtual Data" and verify the array shape.
  6. Process Enrollment: Click Process Enrollment. The engine will generate the topological signature instantly and move the model to your Managed Models list.

 

5. Best Practices

  • Normalization Anchors: For full-body actions, ensure your virtual data has high-integrity movement for the shoulders and hips. These are used for the Torso-Length normalization that makes the model scale-invariant.
  • Synthetic vs. Empirical: When creating a synthetic model (FBX), ensure the motion is not "too robotic." Adding slight organic variance to the animation can often improve real-world detection reliability.
  • SDK Parity: If you are testing these models on the edge, ensure you are using the latest C++ Edge SDK or Python SDK for guaranteed mathematical parity with your virtual data.