Every finding carries a rule ID. IDs are stable: they are never reused or renumbered. A finding is critical
(the robot is broken or will behave wrongly) or a warning (probably a mistake, but the file can load).
rigscan scan --statistics counts findings per rule.
| Rule | Severity | Formats | Flags |
|---|---|---|---|
RS001 |
critical | URDF, MJCF | a joint names a link that is not defined |
RS002 |
critical | URDF, MJCF | two links with the same name |
RS003 |
critical | URDF, MJCF | two joints with the same name |
RS004 |
critical | URDF, MJCF | a link with more than one parent joint |
RS005 |
critical | URDF, MJCF | a kinematic loop |
RS006 |
critical | URDF, MJCF | more than one root link |
RS007 |
critical | URDF, MJCF | a robot with no links |
RS008 |
critical | all | negative link mass |
RS009 |
warning | all | zero mass on a link a joint moves |
RS010 |
critical | all | negative principal moment of inertia |
RS011 |
warning | all | principal moments that break the triangle inequality |
RS012 |
critical | all | joint lower limit above upper |
RS013 |
critical | URDF | a revolute or prismatic joint with no limit, or a limit missing effort or velocity |
RS014 |
critical | URDF, MJCF | a mesh file that does not exist |
RS015 |
critical | URDF | a <mimic> of a joint that does not exist, or of itself |
RS016 |
critical | MJCF | a class or childclass that names no default class |
RS017 |
critical | MJCF | a mesh geom naming an asset that is not defined |
RS018 |
critical | MJCF | an <include> file that does not exist |
RS019 |
critical | USD | a joint that connects a body to itself |
RS020 |
warning | USD | a rigid body with no mass and no collision shape |
RS021 |
warning | USD | joints but no articulation root |
RS022 |
critical | USD | a reference, payload or sublayer that cannot be found |
RS004-RS007 do not run on USD: UsdPhysics joins bodies in a graph, so closed chains and free bodies are valid.
A file that cannot be parsed at all (a bad number, truncated XML) is reported as an error with its line and column,
and rigscan scan exits 2.
A joint's parent or child names a link that does not exist, or has none. Simulators either refuse the file
or silently drop the joint.
<joint name="elbow" type="revolute"><parent link="upper_arm"/><child link="forarm"/></joint>
<!-- forarm is not a link: the child was misspelled -->Fix: use the name of a defined link, or define the missing one.
Two links share a name, so a joint cannot say which one it means. Rename one.
Two joints share a name, so a controller or a <mimic> cannot address one of them. Rename one.
A link is the child of two joints. A rigid body has one pose, so a tree needs exactly one parent per link. Break
the closed chain with a different mechanism (MuJoCo equality, a URDF loop-closure convention).
Following parent to child comes back to where it started. A URDF must be a tree.
<joint name="j1" ...><parent link="a"/><child link="b"/></joint>
<joint name="j2" ...><parent link="b"/><child link="a"/></joint>More than one link has no parent, so the file describes separate robots (or a link was left unconnected). Join them with a joint, or split the file.
The robot has no links. Usually the wrong file or a truncated one.
A link's mass is negative. No physics engine can use it. Fix the sign, or the unit conversion that produced it.
A link that a joint moves has zero mass: it has no inertia, so the dynamics are singular or divided by zero. A massless frame on a fixed joint is fine and is not reported.
<link name="forearm"><inertial><mass value="0"/>...</inertial></link>Fix: give it the mass of the part, or merge it into its parent with a fixed joint.
A principal moment of inertia (an eigenvalue of the inertia tensor) is negative, which no real body has.
The principal moments must satisfy a + b >= c for every pair. A body with ixx = iyy = 0.1, izz = 0.5
cannot exist: its inertia was probably typed in the wrong order or in the wrong units. The file loads, so this is a
warning.
lower is above upper, so the joint has no allowed range. Swap them, or check the unit (URDF radians, MJCF
degrees by default, USD degrees for revolute joints).
A revolute or prismatic joint has no <limit>, or the limit has no effort or velocity. The URDF schema
requires both, and tools such as Pinocchio refuse the file without them. A continuous joint needs none.
<joint name="j" type="revolute"><parent link="a"/><child link="b"/><limit lower="-1" upper="1"/></joint>
<!-- add effort="..." velocity="..." -->A mesh file is not where the description says. The CLI resolves relative paths from the file's directory, and
package://name/... from the nearest parent directory called name; a package it cannot locate is not reported.
<mimic joint="..."> names a joint that does not exist, or the joint it sits in.
A class or childclass names a default class that is not defined, so the settings it was meant to apply are
silently skipped.
<body childclass="missing"><geom type="sphere" size="0.1"/></body>A geom has mesh="ghost" but no <mesh name="ghost"> asset exists.
An <include file="..."> points at a file that is not there, so part of the model is missing.
A joint's body0 and body1 are the same body (or both are the world). It constrains nothing.
A rigid body has no mass (PhysicsMassAPI) and no collision shape, so the engine cannot compute a mass for it.
It loads, with a default mass, so this is a warning.
The stage has joints but no PhysicsArticulationRootAPI, so the joints are solved as loose constraints rather
than as one articulation. Many importers need the root.
A references, payloads or subLayers path could not be found, so part of the stage is missing.
def Xform "robot" (references = @gone.usda@) {}