Verifying Headless Robot Motion: Why Exit Code 0 Lies on 3D Exports

The false reassurance of return code zero in headless CLI tools

In automated 3D synthesis and robotics pipelines, developers rely extensively on command-line utilities operating in headless environments. When converting raw joint trajectory data into industry-standard animation formats like FBX or BVH, scripts dispatch background processes to engines like Blender. Standard software development discipline dictates checking the process exit status: if the command returns code zero, the operational step is registered as successful, and downstream compositing begins.

In 3D animation automation, this assumption is dangerously flawed. During testing of our headless motion generation pipeline on 2026-08-18, automation scripts repeatedly logged successful conversions while downstream game engines loaded empty scenes. Investigating headless Blender 5.1.2 execution logs revealed that the process routinely emits return code 0 even when internal Python operators crash or when source motion files fail to parse.

Never trust a zero exit code from a headless 3D engine; inspect the written artifact directly. Blender considers its CLI execution successful if the application binary boots, executes its script runner, and shuts down without an internal segmentation fault. An unhandled Python exception occurring inside an import operator does not propagate to the operating system shell, masking broken animation exports behind a false exit code 0.

Rigorous re-import verification across FBX bone hierarchies

To prevent corrupt or empty animation files from entering production timelines, our export pipeline enforces a mandatory re-import verification pass. Once the background conversion script completes, an independent verification worker re-opens the resulting FBX file within a clean scene context and programmatically inspects the internal object graph.

The verification script executes a strict structural checklist against the imported armature. It asserts that the file contains exactly 1 armature object, exactly 30 bones matching the Unitree G1 kinematic chain, that the root bone is explicitly named 'pelvis', and that the associated animation action contains a non-zero frame range spanning the requested duration. If any bone is missing or if the root transform is unlinked, the asset is rejected.

Cross-platform testing confirmed that native Linux Blender 5.1.2 generates byte-identical FBX exports matching Windows installations, producing an exact file size of 224,332 B for standardized motion inputs. Operating native Linux binaries inside WSL eliminates path translation overhead while maintaining flawless binary parity.

Channel variance analysis across BVH motion streams

Validating BVH animation files presents distinct challenges. A corrupt export can produce a valid text header and generate a non-zero byte count while containing static, frozen joint values across all frames. Simply checking that a BVH file exists on disk provides no proof that the skeleton actually animates.

Our pipeline parses BVH files using an independent parsing package, evaluating the mathematical variance across all 93 channels. The G1 skeleton comprises 30 joints, producing 6 root translation and rotation channels accompanied by 29 rotational joints carrying 3 Euler channels each (6 + 29×3 = 93 channels total), formatted under ZYX Euler conventions with translation coordinates scaled by 100 from metres to centimetres.

Crucially, verification algorithms must account for single-axis anatomical mechanics. The G1 humanoid knee operates as a mechanical hinge: during locomotion, the knee joint swings dynamically across 73 degrees on its Yrotation channel while remaining completely static at 0.00 on Xrotation. An algorithm evaluating only X-axis motion would falsely flag the knee as broken. In a healthy locomotion cycle, approximately 37 of the 93 channels exhibit dynamic movement, providing a reliable numerical fingerprint of valid skeletal animation.

Calibrating the contact height band for foot-sliding detection

Beyond file integrity, automated motion synthesis requires rigorous kinematic validation to catch physical defects like foot sliding and ground penetration. However, kinematic QA metrics can be actively misleading if geometric thresholds are not calibrated to physical hardware dimensions.

On the Unitree G1 robot, the physical `ankle_roll` body sits approximately 25 mm above the ground plane when the rubber sole is planted, elevating to approximately 190 mm during swing phase. In early test iterations, the validation engine utilized an uncalibrated 120 mm contact height threshold. Because the robot's foot swings through that vertical band during forward stride, the algorithm treated mid-air flight travel as ground contact, reporting 126 mm of severe false foot sliding on perfectly executed walks.

To establish accurate physical discrimination, we calibrated the contact threshold to physical reality: `CONTACT_HEIGHT_M = 0.03` (30 mm), issuing warnings at 20 mm. With this calibrated band, the validator discriminated cleanly between motion styles: `idle` registered 4.2 mm of micro-drift, `stealth_walk` logged 15.8 mm, and standard `walk` recorded 16.9 mm—all cleanly passing QA. Conversely, `walk_zombie` logged 31.1 mm, correctly failing QA due to authentic foot dragging.

Visual ground-truth verification across headless renders

The final stage of the export runbook addresses video rendering. When generating preview MP4 clips via offscreen EGL pipelines piped into ffmpeg, software wrappers frequently confirm valid video headers, standard resolutions, and non-zero byte counts on files where the camera is pointed into empty space or where the character is collapsed.

Our studio mandates pulling a physical frame from the generated MP4 and inspecting its visual contents. An automated test script extracts a frame at midpoint, verifies that the subject bounding box occupies expected frame percentages, and checks that offscreen lighting shaders compiled cleanly. Automated pipelines must never confuse successful file creation with successful creative generation.

By layering structural re-import checks, channel variance analysis, calibrated kinematic thresholds, and visual ground-truth audits, our studio guarantees that headless 3D motion pipelines deliver production-ready assets without human babysitting.