URDF Studio

Inspect, visualize, and drive ROS robot models — in VS Code and in the browser.

Franka FR3 loaded from a local franka_description checkout — full xacro expansion, packages resolved, meshes streamed via blob URLs. The animation cycles through posing the arm, the Source editor, the Checks panel, and back. No server, no install.

Table of contents

• Table of contents
• Quickstart
  • Browser
  • VS Code
• How it looks
  • Main view — joints, panels, 3D viewport
  • Source editor with syntax highlighting, lint markers, and live preview
  • Fullscreen source — IDE mode with a picture-in-picture viewport
  • Checks panel with health score and grouped rules
  • Diagnostics surface as a bottom-corner toast and a populated Checks list
• Features
  • 🖥 Viewing
  • 🦾 Driving
  • 🩺 Analysing
  • 🛠 Authoring
  • 🤖 ROS / URDF / xacro
• Tested models
• Configuration
• Architecture
• Local development
• Contributing & license

Quickstart

URDF Studio ships two artifacts from one codebase. Pick the one that matches how you work.

Browser

1. Open urdf.deyuf.org in Chrome / Edge / Brave / Arc.
2. Click Open Folder → pick a ROS package (try a cloned franka_description).
3. Pick a robot file from the dropdown. The viewport loads on the spot.

Safari / iOS / Firefox don't expose the File System Access API — use the Pick Files button (webkitdirectory fallback) instead. Bytes never leave your machine either way.

VS Code

1. Install deyuf.urdf-studio from the Marketplace — or sideload from source (see below).
2. Right-click a .urdf, .urdf.xacro, or .xacro file → Open With → URDF Studio Preview.
3. The custom editor opens. Workspace package roots are auto-discovered.

Sideload from source:

git clone https://github.com/deyuf/urdf-studio && cd urdf-studio
npm ci
npm run vsce:package                          # produces urdf-studio-<version>.vsix
code --install-extension urdf-studio-*.vsix   # or: VS Code → Extensions → ⋯ → Install from VSIX

Full docs: https://urdf.deyuf.org/docs/.

How it looks

Main view — joints, panels, 3D viewport

The browser app loads a real ROS package off the local disk. Xacro is expanded client-side, every package:// URI is resolved to a blob URL by the host, and meshes stream in via Three.js's LoadingManager. Joint sliders on the right drive the model in real time. The side panel tabs (Joints / Inspector / Checks / Links / Source / Tools) share the same data model — clicking a link in the tree or in the viewport jumps straight to the inspector or the source line.

Source editor with syntax highlighting, lint markers, and live preview

The Source tab is a full CodeMirror 6 editor: URDF-aware highlighting (structural tags, xacro namespace, package:// URIs, ${expr} blocks each get distinct colour), inline lint markers that share rule codes with the Checks panel, intelligent completion (start typing <parent link=" and the editor offers every declared link name), and live preview — edits push through to the 3D viewport after a 160 ms debounce. Ctrl+S saves back to disk (VS Code workspace edit, or FileSystemAccess writable in the browser).

Fullscreen source — IDE mode with a picture-in-picture viewport

Hit F11 (or Ctrl+Shift+F) and the editor takes the whole canvas while the 3D view shrinks into a corner PIP — read a tight 700-line xacro on a small screen without losing the live model preview.

Checks panel with health score and grouped rules

Every diagnostic surfaces here, grouped by rule code (R-xxx structural, P-xxx physics, A-xxx assets, S-xxx style/xacro). A 0–100 health score quantifies overall fitness — useful when iterating on a model to clear errors quickly. Click any row to jump to the offending line in the Source tab.

Diagnostics surface as a bottom-corner toast and a populated Checks list

When the parser or analyser finds problems, they surface two ways at once. Every diagnostic shows up in the Checks panel grouped by rule code (with severity, message, and source line). Errors and warnings also trigger a bottom-corner toast that pops up automatically and links the user back to the Checks panel; error toasts stick until dismissed, warning toasts auto-fade.

Features

Feature pages in the docs go into much more detail; this is the overview.

🖥 Viewing

🦾 Driving

🩺 Analysing

🛠 Authoring

🤖 ROS / URDF / xacro

Tested models

End-to-end Playwright smoke test against the upstream franka_description package. Reproducer:

git clone https://github.com/frankarobotics/franka_description /tmp/franka_description
npm run web:build
FRANKA_DIR=/tmp/franka_description node scripts/test-franka.mjs

The whole pipeline runs in the browser: directory pick, xacro expansion (including load_yaml for joint limits / inertials YAMLs), package resolution, mesh blob URL allocation, Three.js render.

Configuration

Both targets expose the same five settings.

Web: ⚙ button in the topbar → JSON in localStorage. VS Code: urdfStudio.* keys in settings.json.

Details: docs/features/settings →

Architecture

A single TypeScript codebase produces both targets:

                src/core/                 — pure logic, no fs/path/DOM imports
                     ▲
       ┌─────────────┴─────────────┐
   io.node.ts                   ioBrowser.ts
   (jsdom + node:fs)            (FileSystemAccess + native DOM)
       ▲                              ▲
  src/extension.ts               src/web/host.ts
       ▲                              ▲
       └─────────── postMessage ──────┘
                     ▼
              src/renderer/main.ts     — Three.js + URDFLoader, identical

The core never touches Node-only modules directly; it queries a CoreIo interface set by the host. The renderer is bundled separately and is identical on both targets — the only thing that differs is the postMessage source.

Deep dive: docs/architecture →

Local development

git clone https://github.com/deyuf/urdf-studio
cd urdf-studio
npm ci

Common loops:

# VS Code extension
npm run watch              # incremental rebuild; press F5 in VS Code

# Web app
npm run web:dev            # http://127.0.0.1:5173 with HMR

# Docs only
npm run docs:watch         # rebuild dist-web/docs on every .md change

# Tests
npm run test:unit          # 24 node:test cases on src/core
npx playwright test        # 19 renderer + web shell specs

# Real-world smoke
FRANKA_DIR=/tmp/franka_description node scripts/test-franka.mjs

Production builds:

npm run package            # VS Code extension (dist/)
npm run web:build          # web app + docs (dist-web/)
npm run vsce:package       # .vsix for sideload / Marketplace
# then: code --install-extension urdf-studio-*.vsix

More: docs/development/building →

Contributing & license

PRs welcome.

License: MIT.