URDFKit

A modular Swift package for parsing, animating, and rendering robots described in URDF format.

Platforms: iOS 17+ · visionOS 1+ · macOS 14+
Swift: 6.0+

Features

• 🤖 URDF parsing — Foundation.XMLParser-based, no external dependencies
• 🔗 Mimic joints — automatic dependent joint expansion with cycle detection
• 📐 Forward kinematics — compute link poses from joint positions
• 🗄️ Mesh loading — OBJ/STL via Apple Model I/O (no USDZ conversion)
• 🎮 RealityKit rendering — builds Entity tree from parsed robot
• 🧊 Debug renderer — boxes + axes for quick kinematics validation
• 📦 Modular — pick only the products you need (see BACKENDS.md)

Quick Start

Open the SampleApp

1. Open SampleApp/URDFKitSample.xcodeproj in Xcode
2. Select the iOS, visionOS, or macOS scheme
3. Build and run
4. The app loads a bundled sample robot — use sliders to move joints

Run Tests

cd /path/to/swiftURDF
swift test

Tests run on macOS and cover:

• URDF parsing
• Math utilities (transforms, quaternions)
• Mimic joint expansion + cycle detection
• Forward kinematics
• Geometry primitives
• Mesh cache
• Asset URI resolution
• RobotRuntime joint propagation

Run the CLI

swift run urdfkit-cli validate path/to/robot.urdf
swift run urdfkit-cli dump path/to/robot.urdf
swift run urdfkit-cli resolve-meshes path/to/robot.urdf --package-map my_robot=/path/to/pkg

validate reports joint counts (including fixed joints used for frames/attachments), independent DOF, and any mimic joints.

Package Integration

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/<you>/swiftURDF.git", branch: "main"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "URDFKitRealityKit", package: "swiftURDF"),
        ]
    ),
]

See Docs/BACKENDS.md for how to pick individual modules.

Module Overview

Module	Purpose
URDFKitCore	Data layer: model + math + URDF parsing + asset resolution
URDFKitRuntime	Computation layer: kinematics + geometry primitives/mesh data
URDFKitRender	Render-agnostic runtime + scene description + mesh IO + Model I/O importer
URDFKitRealityKit	RealityKit renderers + convenience umbrella exports

See Docs/ARCHITECTURE.md for the full dependency graph.

Documentation

• ARCHITECTURE.md — Module responsibilities and design rules
• URDF_SUPPORT_MATRIX.md — Supported URDF tags and formats
• BACKENDS.md — How to pick and add backends

License

MIT