Research Tools

Traverses the entire USD prim tree and prints a human-readable summary of all prims, their types, and active APIs. Specifically identifies ArticulationRootAPI, RigidBodyAPI, CollisionAPI, and JointAPI applications. Essential first step before any modification.

python research_tools/inspect_usd.py \
  --usd /path/to/robot.usd

Performs a validation pass on a USD file: verifies that exactly one prim has ArticulationRootAPI, that no FixedJoint connects to the world frame, and that the default prim is set. Reports PASS/FAIL for each check with detailed diagnostic output.

python research_tools/check_usd.py \
  --usd /path/to/robot.usd

The primary articulation repair script. Opens a USD as a sublayer, deactivates the root_joint prim that pins the robot to the world, and applies UsdPhysics.ArticulationRootAPI + PhysxSchema.PhysxArticulationAPI to the chassis body. Writes output as a new USD file (non-destructive).

python research_tools/fix_lekiwi_usd.py
# Input:  assets/robots/lekiwi/lekiwi.usd
# Output: assets/robots/lekiwi/lekiwi_floating.usd

Scans a USD for all prims with UsdPhysics.CollisionAPI applied. Prints a count and list of all collision prim paths. If the count is zero, the robot is a "ghost" — it has no physics surface and will fall through the floor or not generate traction.

python research_tools/find_collisions.py \
  --usd /path/to/robot.usd
# Output: "Found 0 collision prims" → ghost robot!

Procedurally injects collision geometry into a robot USD. For each configured wheel body path, creates a child collision prim: Cylinder for drive wheels (traction), Sphere for passive caster wheels (free rolling). Also disables self-collisions at the articulation level to prevent NaN explosions.

python research_tools/add_wheel_collisions.py
# Input:  lekiwi_floating.usd
# Output: lekiwi_final.usd

Key configuration at the top of the file:

WHEEL_RADIUS = 0.0325 * 0.95  # 5% smaller prevents ground interpenetration
WHEEL_WIDTH  = 0.03            # cylinder height in meters
WHEEL_BODIES = ["/LeKiwi/wheel_body_1", ...]
# is_caster = (i == 2)  → 3rd wheel gets Sphere shape

More general collision injection script (precursor to add_wheel_collisions.py). Supports adding Box, Sphere, and Cylinder shapes to arbitrary prim paths, with configurable dimensions and material bindings. Useful for adding body colliders in addition to wheel colliders.

Physics validation script that loads a USD in IsaacSim, spawns the robot, applies motor commands at a fixed velocity, and reports: wheel joint velocities, base translation velocity, contact forces, and any NaN detection. Designed to be run after add_wheel_collisions.py to confirm that the robot actually moves.

python research_tools/check_wheel_physics.py
# Runs 500 simulation steps, prints:
# - Joint vel: [14.2, 16.1, 0.0] rad/s
# - Base vel:  [0.0, 0.0, 0.0] ← still the traction problem!

Prints a complete list of all joints in the USD articulation tree with their types (RevoluteJoint, PrismaticJoint, FixedJoint), parent/child body paths, and current axis definitions. Critical for identifying the root_joint that needed to be deactivated.

Minimal sanity check script. Opens a USD without launching the full simulation app, prints the prim tree structure, and checks for the most common integration errors. Useful for quick iteration without the 30-second Isaac Sim startup cost.