Metriplane Turns Robot Workcell Failures Into Checksummed, Replayable Evidence

When an industrial robot workcell grinds to a halt, the aftermath is usually a pile of ambiguous data: timestamped middleware messages, application logs, execution traces, simulator recordings, and hastily typed operator notes. Each source captures a fragment of what happened, but none of them determines which state transition actually counts as a process deviation, which interval of time belongs to the incident, or whether a later run constitutes a recurrence of the same failure. Those interpretive decisions typically live in local scripts or informal notes, making them nearly impossible to review across software revisions or outside the team that wrote them. A new open-source tool called Metriplane, described in the journal SoftwareX, aims to close that gap by turning workcell failures into reproducible, checksummed evidence bundles that anyone can verify and replay.

Developed by Miko Parkkinen, Metriplane version 0.2.0 is a Python package that sits downstream of the recording infrastructure familiar to robotics teams. Rather than replacing tools like rosbag2, which captures serialized message streams in the ROS 2 middleware, or runtime tracing frameworks that expose internal execution timing, Metriplane consumes their outputs after they have been translated into a schema-conforming format called the FrameStateModel. Each accepted record carries run, time, frame, object, and planar position fields, enriched by an asset registry, workspace zone definitions, and a YAML process specification that describes the steps the cell is supposed to perform.

The heart of the system is an evaluator called Atlas, which processes each replayed frame against the configured process rules and emits typed events into a chronological JSONL ledger. From these events it derives deviations, groups related events into incidents, and produces a human-readable chronology the project calls a Cell Truth Report. Crucially, the report’s name is a project-defined label rather than a claim of independently established physical ground truth. Measured state, configured interpretation, incident packaging, and review output remain deliberately separate, so a reviewer can inspect the exact rule that produced an event and the files supporting an incident without ever touching live hardware.

The demonstration scenario is a camera-free assembly-cell replay in which a torque driver goes missing. Five state records arrive at 0, 10, 20, 55, and 70 seconds. At the 20-second record, the tool torque_driver_1 is first evaluated as absent for a step whose configured maximum wait is 30 seconds. Because Atlas evaluates conditions as each replay record arrives, the first record after the threshold, at 55 seconds, yields a step_delayed event reporting exactly 35.0 seconds, a value derived directly from the discrete timestamps rather than interpolation. Across the 70-second run, the evaluator writes six events, one deviation, and one warning-level incident, INC-0001, which links a required_asset_missing event and the step_delayed event to an incident type labeled missing_tool_caused_delay. The authors are careful to note that this identifier is an implementation-defined label, not proof that the missing tool caused the delay.

Every incident is packaged into an evidence bundle, a 16-file archive containing the incident record, matching event excerpts, the replay state segment, configuration snapshots, the report, replay and provenance commands, a manifest, stated limitations, and SHA-256 checksums. A local verifier checks required paths, the bundle schema version, the listed checksums, safe ZIP extraction, and whether the event timeline contains every event the incident references. This structure draws on established provenance and research-object packaging principles, though Metriplane does not claim formal conformance to standards like PROV or RO-Crate. Compared against adjacent systems such as ROSMonitoring, HAROS, and the robot evidence tool Flightcase, the distinguishing contribution is the specific integration: rule-derived events linked to incidents, a checksummed bundle, and a generated replay check drawn from the same package.

That replay check is the tool’s most distinctive feature, and it is deliberately narrow. The generated regression YAML records the expected event type, asset, process step, and severity, along with the expected incident type and severity, but intentionally omits the original event identifiers. A rerun may assign new event IDs and still pass. The runner first verifies the source bundle, replays its state segment with the bundled configuration, and then looks for events and an incident matching the expected fields. This presence-based design separates provenance linkage within the bundle from the fields used as the regression oracle, ensuring the check remains meaningful even when identifiers shift between runs.

The reproducibility story is unusually rigorous for this kind of software. The published tag v0.2.0 is archived on Zenodo with a fixed commit identifier, while the evidence package was captured at a separate pre-release commit four commits earlier. The author documents that the intervening changes touched only release documentation, packaging, and ignore rules, leaving the runtime and benchmark source untouched. A single-command wrapper script creates a fresh temporary checkout, verifies the exact commit, and executes the full core sequence: deterministic replay, domain pack validation, incident evaluation, bundle verification, and the generated regression check, all writing only to temporary directories so reviewers cannot overwrite archived evidence.

Independent scrutiny adds weight to the claims. The author-run maintainer test gate passed 580 tests in 68.35 seconds on Ubuntu 24.04 with Python 3.12.3, and the replay comparison showed 24 matched frames, 72 matched object pairs, and 0.0 centimeter mean and maximum position difference with zero matched-object zone-field mismatches. A public independent reproduction on macOS with Python 3.13.7 successfully reproduced the core workflow, including the six-event result, bundle verification, and generated check, though the full test suite retained two failures in that environment, a caveat the paper reports transparently rather than hiding. Revision-only controls further characterized the oracle: a no-incident run with the tool present produced four events and zero incidents, while an intentionally absent expected event correctly returned pass=false with exit code 4.

The limitations are stated with equal candor. Incident recognition depends entirely on the supplied process and spatial rules, so unforeseen failures may be missed and incorrect rules may produce misleading interpretations. The planar state model assumes tracked or tagged assets, and the bundle does not retain raw perception data that might explain glare, occlusion, or calibration drift. The verifier does not enforce complete checksum coverage of every file, and the presence-based check asserts nothing about event order, count, timing, duration, or unexpected additional events. Static replay also excludes controller or learned-policy interaction, and reviewer usability has not been formally evaluated.

Those boundaries frame the future agenda. Near-term engineering priorities include enforcing temporal tolerances, event order, cardinality, and unexpected-output rules, plus incident fingerprinting. Experimental validation should extend to multiple workcells, held-out failures, and additional cross-platform reproductions, while longer-term research points toward closed-loop hardware-in-the-loop behavior, explicit ROS bag adapters, and evidence review in digital-twin settings. For now, Metriplane demonstrates something deceptively simple but genuinely useful: a traceable chain from replayed state through configured events to a checksummed bundle and a deterministic check, released under the MIT license for anyone building robots who has ever stared at a log file wondering what actually went wrong.

Subject of Research: Reproducible incident evidence and replay-based regression checking for robotic workcells

Article Title: Metriplane: Reproducible incident evidence and presence-based replay checks for bounded workcells

Article References: Parkkinen, M. (2026). Metriplane: Reproducible incident evidence and presence-based replay checks for bounded workcells. SoftwareX, 36, Article 103104. https://doi.org/10.1016/j.softx.2026.103104

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103104

Keywords: Metriplane, robotics, ROS 2, incident evidence, reproducibility, regression testing, evidence bundles, digital twins, workcell automation, SHA-256 checksums, replay verification, open-source software