Articulate Arena

1Overview

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 E_B under the kinetic-energy norm, and superscripts mark the extensions E^ϕ (compactified) and E^tree (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.

2Installation

articulatearena will be published to PyPI once the source is available. It requires Python ≥ 3.10 and depends only on numpy, scipy, and pyyaml. The following will be the install command:

$ pip install articulatearena

To work from a source checkout instead, run pip install -e . at the repository root. The editable install registers the same import name, and the bundled scripts also run without installation, as they place the package directory on sys.path themselves.

3Quickstart

Build endpoint pairs for two joints, choose an se(3) norm, and evaluate joint_metric. The distance is 0 exactly when the two joints induce the same motion:

import numpy as np
from articulatearena.new_equation.representation import make_endpoint_pair
from articulatearena.new_equation.inner_product import make_split_norm
from articulatearena.new_equation.E import joint_metric

xi = np.array([0., 0., 1., 0., 0., 0.])   # unit screw axis (omega; nu)
gt   = make_endpoint_pair(xi, 0.0, 1.0)    # joint limits [a, b]
pred = make_endpoint_pair(xi, 0.0, 1.0)

norm = make_split_norm(alpha=1.0)          # the norm is injected, never hardcoded
E = joint_metric(gt.u.data, gt.v.data, pred.u.data, pred.v.data, norm)
print(E)   # 0.0 when prediction == ground truth

To score real URDF joints, load them through the reader layer instead of constructing twists by hand:

from articulatearena.read.urdf_loader import load_joint
from articulatearena.new_equation.representation import joint_to_endpoint_pair

joint = load_joint("sample_data/45168/mobility.urdf", "joint_0")
pair  = joint_to_endpoint_pair(joint)      # unordered {a*xi, b*xi}

4Core concepts, as a tutorial

This section is the long version of the paper's Section 3, written for ourselves. Each concept gets its own figure, drawn by scripts/make_tutorial_figures.py with every number computed by the library, and a short list of the confusions it is meant to clear up. The paper's notation is kept throughout.

4.0 Notation cheat sheet

4.1 A joint is a twist

A URDF describes a joint with four separate things: a type, an axis direction a, an origin o, and limits. The first three are really one object, an infinitesimal rigid motion, and that object is the twist ξ = (ω, v). A revolute joint rotates about the line through o with direction a, which is ξ_rev = (a, o × a). A prismatic joint slides along a and has no rotation at all, ξ_pris = (0, a). A helical joint adds a translation of h meters per radian along the axis, ξ_hel = (a, o × a + h a). Flowing along ξ for q units gives the placement exp(q ξ̂) g₀ of the child link, where g₀ is the placement stored in the file.

4.2 The endpoint pair

Multiply the unit twist by the two limits and the joint becomes a pair of points in se(3), {z⁻, z⁺} = {l⁻ ξ, l⁺ ξ}. The direction of the segment is the screw, its length is the range, its position along the line is where the range sits relative to the anchor. Nothing about the joint is lost and nothing about it is duplicated. The segment passes through the origin whenever l⁻ ≤ 0 ≤ l⁺, that is, whenever the stored state is inside the range. The fixed joint is the degenerate segment {0, 0}.

4.3 The metric E and the ℤ₂ swap

Two unordered pairs can be matched in two ways, direct (z₁⁻ ↔ z₂⁻, z₁⁺ ↔ z₂⁺) or swapped. Each way has a flat distance in se(3) × se(3), the square root of the two squared endpoint differences, and

E(J₁, J₂) = min{ ‖z₁⁻ − z₂⁻‖² + ‖z₁⁺ − z₂⁺‖², ‖z₁⁻ − z₂⁺‖² + ‖z₁⁺ − z₂⁻‖² }^1/2.

This is the quotient distance of a flat space by the group ℤ₂ acting as the swap, and a quotient by a finite group of isometries is again a metric. That single fact gives the triangle inequality, which no hand-built combination of component errors has.

4.4 Wrap and gauge symmetries

A revolute exponential is 2π-periodic, so shifting both limits by 2πk rewrites the same motion over the same anchor. The definition of E uses the limits exactly as stored, so such a pair of encodings is charged the shift. As an optional preprocessing step, wrap_revolute_limits shifts a revolute joint's limits by the common 2πk that places the midpoint ½(l⁻ + l⁺) in [−π, π), and joint_to_endpoint_pair(joint, wrap_revolute=True) applies it before forming the pair. Only revolute joints can be wrapped: a prismatic shift translates and a helical shift also translates, so for them k = 0 is forced.

A prismatic twist is (0, a) and contains no origin at all, so moving the drawn origin is pure gauge and the metric returns zero. The prior origin score charges ‖o₁ − o₂‖ for it. For a revolute joint the origin matters through the moment, which is the physically right behavior: a hinge on a different line moves the door differently.

4.5 Which norm: E_α versus E_B

The formula for E only asks for a norm on twist differences Δz = (Δω, Δv) that comes from an inner product. Two are offered, and the subscript on E says which one is inside.

The split norm ‖Δz‖_α² = ‖Δω‖² + α²‖Δv‖² weighs rotation against translation through one inverse length α. It needs no geometry, is dimensionless, and compares every joint of every object by one rule. The kinetic-energy norm ‖Δz‖_B² = (1/m) Δωᵀ I Δω + ‖Δv + Δω × c‖² lets the moving link set the scale: m, c, and I are the mass, center of mass, and inertia of the ground-truth child link. Under it E_B is in meters and equals the RMS linearized motion of the link's material.

4.6 Continuous joints and the compactification E^ϕ

A continuous joint has l^± = ±∞, so its endpoint twists are at infinity and the flat distance is undefined. The radial map ϕ(z) = tanh(‖z‖/κ) z/‖z‖ pulls all of se(3) into the open unit ball and sends the continuous joint to the antipodal boundary pair {±ξ/‖ξ‖}, the axis direction up to sign. Then E^ϕ(J₁, J₂) = E({ϕ(z₁⁻), ϕ(z₁⁺)}, {ϕ(z₂⁻), ϕ(z₂⁺)}). Against a continuous ground truth with unit screw, a finite prediction [−L, L] on the same screw scores √2 (1 − tanh(L‖ξ‖/κ)): it starts at √2, the distance from the welded joint, and decays to zero. A continuous joint is literally the limit of a growing range, with no formula switch.

4.7 Trees: E^tree and the assignment relaxation

An object is a tree with links as nodes and joints on the edges, and the same object admits many trees: parts can be relabeled, the base re-chosen, a handle welded to a drawer or split off. The tree metric is the cheapest sequence of edits from one tree to the other, E^tree(T₁, T₂) = inf_π Σ_o∈π c(o), with substitution costing E(J, J′) and contraction or expansion costing E(J, J₀). A spurious joint that barely moves costs ε‖ξ‖, not a constant penalty, so topology errors and joint errors are priced in the same motion currency and the metric is continuous through the welded boundary. Exactly fixed edges are contracted first (contract_small_edges) because they are representation noise.

Any edit sequence can be reordered into contract, then substitute along a tree isomorphism, then expand. The exact distance is therefore a minimum over matchings of the edge sets that extend to an isomorphism of the contracted trees. Dropping that realizability condition gives the assignment relaxation: a Hungarian matching over the joint multisets with E(J, J₀) as the unmatched cost (assignment_tree_distance). It is always a lower bound, it is polynomial for any input, and it needs only the multiset of predicted joints. Whenever its optimal matching happens to be realizable, checked in linear time by matching_realizable, the relaxation certifies the exact value. exact_tree_distance returns (distance, certified) and falls back to a small constrained search otherwise.

4.8 Reading the table headers

The rule is simple once seen: the subscript is the inner product inside the norm, the superscript is what was done to the endpoints before or after E. The design space is the product of the two choices, and any cell of it is a legitimate score.

5API reference

Public functions and classes, by module. All array arguments are NumPy float64, and twists are shape (6,) in the paper's convention ξ = (ω, v).

Types · articulatearena.types

Representation · new_equation.representation

Joint metric · new_equation.E

Norms · new_equation.inner_product

Continuous joints · new_equation.continuous

Tree metric · new_equation.tree

Skeleton distance · new_equation.skeleton

Material motion · new_equation.material_motion

Background math · general_equation

I/O · read and write

Baselines · previous_metrics.component_scores

Component scores of prior evaluation templates (type, axis, origin, and limit errors with thresholded joint_success), kept for reproducing §3-style baseline numbers.

6Command-line usage

The repository entry point evaluates a prediction/ground-truth case end to end. It loads the config, runs the pure metric functions, and writes a report:

$ python scripts/run.py --config configs/default.yaml
# → Report written to out/metrics_report.json

configs/default.yaml groups the knobs that the paper treats as caller-supplied:

Auxiliary scripts: scripts/generate_error_cases.py synthesizes controlled error cases from a URDF, scripts/run_previous_metrics.py scores the same cases with the baseline component metrics, and examples/run_real_cases.py evaluates real PartNet-Mobility objects.