Skip to main content
Version: dev-latest

Spec From URDF

Usage​

Spec From-URDF - CLI Example
metrical spec from-urdf [OPTIONS] <URDF_FILE>
Spec From-URDF - Manifest Example
command = "spec-from-urdf"
input-urdf = "{{variables.urdf}}"
output = "{{auto}}"
topic-prefix = "/"
strip-prefix = "robot_"

Purpose​

metrical spec from-urdf converts a ROS URDF file into a system specification JSON file. It extracts the fixed-joint transforms from the URDF to populate the mechanical_layout, and optionally sets camera_bases and camera_field_of_view for specified camera links.

This is useful when your sensor rig is already described in a URDF; rather than transcribing transforms by hand, you can generate a system specification directly and then pass it to metrical plex learn.

What gets extracted​

  • Fixed joints only: Only URDF joints of type fixed are included in the output. Revolute, prismatic, and other movable joint types are skipped, since they do not represent rigid mechanical relationships.
  • Translation and rotation: The <origin xyz="..." rpy="..."/> element on each fixed joint is converted into a translation vector and a unit quaternion. The URDF RPY (Roll-Pitch-Yaw) Euler convention is handled automatically.
  • Directionality: Each fixed joint produces a mechanical_layout entry where from is the child link and to is the parent link.

Topic name mapping​

URDF link names often differ from the topic names used in your dataset. The --strip-prefix, --topic-prefix, and --remap options let you transform URDF link names into the topic names that MetriCal expects.

The transformation pipeline for each link name is:

  1. If the link has an explicit --remap entry, use the remapped name directly (skip steps 2 and 3).
  2. If --strip-prefix is set and the link name starts with that prefix, remove it.
  3. If --topic-prefix is set, prepend it to the (possibly stripped) name.

After all names are resolved, the command validates that no two URDF links map to the same topic name.

Camera properties​

URDFs do not distinguish cameras from other sensor types, so MetriCal cannot automatically detect which links are cameras. Use the --camera flag to specify camera links along with their coordinate basis and optional diagonal field of view. These values populate the camera_bases and camera_field_of_view sections of the output.

ROS optical frames

ROS URDFs often define two links per camera: a physical mount link (e.g. camera_link, typically in the FLU convention) and an optical frame link (e.g. camera_optical_frame, rotated to RDF). Point --camera at whichever link you want in your system specification and set the basis to match that frame's convention. If --camera is omitted for a camera link, metrical plex learn defaults to RDF.

Examples​

Basic conversion​

metrical spec from-urdf robot.urdf -o system_spec.json

With camera properties and topic prefix​

metrical spec from-urdf robot.urdf \
    --camera left_cam:FLU:90 \
    --camera right_cam:RDF \
    --topic-prefix / \
    -o system_spec.json
metrical spec from-urdf robot.urdf \
    --strip-prefix robot_ \
    --topic-prefix /sensors/ \
    -o system_spec.json

This transforms a URDF link named robot_left_camera into the topic name /sensors/left_camera.

metrical spec from-urdf robot.urdf \
    --remap imu_link:/imu/main \
    --remap cam_front:/camera/front \
    --topic-prefix / \
    -o system_spec.json

Remapped links bypass --strip-prefix and --topic-prefix entirely; non-remapped links still go through the normal transformation pipeline.

Pipe the output into plex learn​

metrical spec from-urdf robot.urdf \
    --camera left_cam:FLU:90 \
    --strip-prefix robot_ \
    --topic-prefix / \
    -o system_spec.json

metrical plex learn \
    -S system_spec.json \
    --dataset data.mcap \
    -m '*camera*:opencv-radtan' \
    -m '*lidar*:lidar' \
    -o plex.json

Arguments​

<URDF_FILE>​

The path to the input URDF file. The file must be valid URDF XML.

Options​

Global Arguments​

As with every command, all global arguments are supported (though not all may be used).

-o, --output [OUTPUT]​

The path to output the resulting system specification JSON file. Defaults to system_spec.json.

-c, --camera [LINK:BASIS[:DFOV]]​

Specifies a URDF link to treat as a camera, along with its coordinate basis and an optional diagonal field of view in degrees.

The format is LINK:BASIS or LINK:BASIS:DFOV, where:

  • LINK is the URDF link name (before any prefix stripping or remapping).
  • BASIS is a three-character coordinate basis string (e.g. FLU, RDF). See camera_bases for the full list of valid bases.
  • DFOV (optional) is the nominal diagonal field of view in degrees.

This flag can be repeated for multiple cameras:

--camera left:FLU:90 --camera right:RDF

The specified link must exist in the URDF and must be part of a fixed joint. If a camera link appears more than once, the command will return an error.

--topic-prefix [PREFIX]​

A string to prepend to each URDF link name when generating topic names. For example, --topic-prefix / transforms the link name left_camera into /left_camera.

Applied after --strip-prefix but skipped for links that have an explicit --remap entry.

--strip-prefix [PREFIX]​

A prefix to remove from each URDF link name before applying --topic-prefix. For example, --strip-prefix robot_ transforms the link name robot_left into left.

If a link name does not start with the given prefix, it is left unchanged. Skipped for links that have an explicit --remap entry.

-r, --remap [OLD:NEW]​

Remaps an individual URDF link name to a specific topic name. The format is OLD:NEW, where OLD is the original URDF link name and NEW is the desired topic name.

When a link matches a remap entry, the remapped name is used directly; --strip-prefix and --topic-prefix are not applied to that link.

This flag can be repeated for multiple remaps:

--remap robot_cam:left_camera --remap robot_lidar:/sensors/lidar

The OLD name must match an existing link in the URDF. After all remaps are applied, the command validates that no two links resolve to the same topic name.