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

On a 2K display (2560 × 1440), the inspector stays at a readable width while the viewport takes the remaining space. Layout regression checks also cover 150% display scaling.

2K workspace and settings menu

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.

Releases

Merges to main automatically select a stable version, run the complete test suite against the candidate VSIX, publish it to the Marketplace, and create a GitHub Release. No manual version bump is needed. develop and design/quiet-studio pushes publish beta builds after the same checks.

Stable versions advance above any newer beta (for example, 0.5.x beta → 0.6.0 stable), so users on the beta channel can upgrade. Failed runs reuse their release checkpoint when rerun. See release automation for version rules, artifacts, and recovery.

Configuration

Both targets expose the same five settings.

Workspace: Camera presets and geometry layers sit inside the viewport; Display contains grids, frames, labels, and diagnostic overlays. Drag the inspector divider to resize it, or focus it and use the arrow keys. Joint controls pair full-width sliders with numeric values and units. Checks are grouped into collapsible sections with source links. Export collects PNG, pose JSON, parts CSV, and inspection PDF exports.

Colors: Classic colors in the Settings (gear) menu switches between the original palette and the new Studio palette in both the browser and VS Code. The choice is remembered independently of the light/dark theme.

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          # core, editor, renderer logic, and browser storage
npm run test:renderer      # builds both targets, then runs browser tests
npm run test:vscode        # real VS Code integration (Linux: use xvfb-run)

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

Regenerate the PNG icon from its SVG master:

node scripts/build-icon.mjs
# Set CHROMIUM_PATH=/usr/bin/chromium to use an installed browser.

Refresh the README screenshots and animation (requires ffmpeg and a full Franka mesh directory; the checked-in xacro fixture pins the model definition):

cp -a test/fixtures/franka_description /tmp/urdf-readme-franka
cp -a /path/to/franka_description/meshes /tmp/urdf-readme-franka/meshes
npm run web:build
FRANKA_DIR=/tmp/urdf-readme-franka node scripts/capture-screenshots.mjs
# Set CHROMIUM_PATH=/usr/bin/chromium to use an installed browser.

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.