ArticulateArena
Usage documentation for articulatearena, the reference implementation of the quotient metric E on one-degree-of-freedom articulated joints and its object-level lifts.
Section 1
Overview
How well does a predicted object move?
ArticulateArena evaluates the motion and connections of articulated objects. Start with a cabinet, follow one example through the concept map, then connect it to the metric below.
Start with something familiarWhat is an articulated object?
Watch the parts move, or choose Explore to connect each part to its place in the tree.
This cabinet is an articulated object with three main parts: the body, drawer, and door. The drawer slides and the door rotates relative to the body.
Four ideas to keep with you
- Link
- One rigid part.
The door, the drawer, or the body. - Joint
- A connection with a motion rule.
A hinge lets the door rotate. - One degree of freedom
- One number sets the joint’s state.
A distance for a slide; an angle for a hinge. - Kinematic tree
- A map of the connections.
Parts are nodes. Joints are edges.
Does the predicted object move and connect like the reference?
ArticulateArena measures that difference. This tutorial considers objects whose connections form a tree.How the cabinet’s parts are connected
An articulated object has parts that can move relative to each other. Each rigid part is a link; each connection that controls their relative movement is a joint.
This simplified example adds a turning latch to the drawer, so we can follow a joint attached to another moving part.
Where does “one degree of freedom” fit?
For each moving joint here, one number sets its configuration: the drawer’s opening distance, the door’s angle, or the latch’s angle. The whole cabinet has several joints, so it needs several numbers.
The tree is a map of these connections. Articulated objects can also have closed loops; this tutorial and the paper’s tree score focus on tree structures.
Now imagine a model predicts this cabinet. Its drawer might stop too early, or its latch might be attached to the wrong part. We need to compare both how each joint moves and how the parts connect.
The map below follows that comparison from an object to a score. Choose an example first; each stage shows what goes in, what comes out, and where to read the details.
The evaluation processThree stages of articulation evaluation
Compare how parts can move, then include how they connect.
Reference + prediction
Read the introduction ↑The notation, when you need it
From the map to the mathematicsThe metric behind the map
The map turns a joint’s movement rule and limits into two endpoint vectors. The formula below compares those endpoints in both pairings and keeps the smaller distance: the joint error E.
articulatearena implements a principled distance between articulated-kinematics
predictions and ground truth. A one-DOF joint
J = (ξ, [l⁻, l⁺]) with unit screw twist ξ ∈ se(3)
and limits l⁻, l⁺ is represented by its unordered pair of
endpoint twists {z⁻, z⁺} = {l⁻ξ, l⁺ξ}. The joint metric is the
quotient distance of flat se(3) × se(3) under the swap:
E(J₁, J₂) = min{ ‖z₁⁻ − z₂⁻‖² + ‖z₁⁺ − z₂⁺‖², ‖z₁⁻ − z₂⁺‖² + ‖z₁⁺ − z₂⁻‖² }1/2,
where ‖·‖ is an injected se(3) norm. A subscript names that choice, Eα under the split norm and EB under the kinetic-energy norm, and superscripts mark the extensions Eϕ (compactified) and Etree (tree lift). The package provides the metric itself, a smooth training surrogate, the radial compactification that extends the metric continuously to unbounded (continuous) joints, and two object-level lifts: an optimal-assignment skeleton distance and a motion-aware tree edit distance with a certified assignment relaxation.
All functions are pure: norms, weights, and tolerances are passed in by the caller and never hardcoded.
The library depends only on numpy, scipy, and pyyaml.