URDF Loader for Three.js

一个专为Three.js设计的URDF（Unified Robot Description Format）模型加载器，支持完整的机器人模型加载、可视化和交互。

🚀 功能特性

• 🔧 URDF支持: 完整支持URDF和XACRO格式的机器人模型
• 🎨 多格式支持: 支持GLTF、GLB、OBJ、STL、DAE等多种3D模型格式
• ⚡ 高性能: 优化的加载器和渲染性能
• 🎯 交互控制: 内置关节控制和动画系统
• 📱 响应式: 支持移动端和桌面端
• 🔍 调试工具: 内置可视化调试工具
• 📦 TypeScript: 完整的TypeScript类型支持，严格的类型安全
• 🛠️ 模块化: 清晰的模块化架构，易于扩展
• 🔒 封装性: 完善的访问修饰符，保护内部实现
• 🔄 异步加载: 现代化的Promise-based异步加载API

📦 安装

npm install @feng3d/urdf-loader

或者使用yarn：

yarn add @feng3d/urdf-loader

🎯 快速开始

基本使用

import { URDFLoader } from '@feng3d/urdf-loader';
import { Scene, WebGLRenderer, PerspectiveCamera } from 'three';

// 创建场景
const scene = new Scene();
const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new WebGLRenderer();

// 创建URDF加载器
const loader = new URDFLoader();

// 异步加载机器人模型
const robot = await loader.load('robot.urdf');
scene.add(robot);
console.log('机器人加载完成！');

使用Promise方式

import { URDFLoader } from '@feng3d/urdf-loader';

const loader = new URDFLoader();

loader.load('robot.urdf')
  .then(robot => {
    scene.add(robot);
    console.log('机器人加载完成！');
  })
  .catch(error => {
    console.error('加载失败:', error);
  });

自定义材质加载

import { URDFLoader } from '@feng3d/urdf-loader';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader';
import { STLLoader } from 'three/examples/jsm/loaders/STLLoader';

const loader = new URDFLoader();

// 自定义网格加载回调
loader.loadMeshCb = (path, manager, done) => {
    const ext = path.split(/\./g).pop().toLowerCase();
    
    switch (ext) {
        case 'gltf':
        case 'glb':
            new GLTFLoader(manager).load(path, result => done(result.scene));
            break;
            
        case 'obj':
            new OBJLoader(manager).load(path, result => done(result));
            break;
            
        case 'stl':
            new STLLoader(manager).load(path, result => {
                const material = new MeshPhongMaterial();
                const mesh = new Mesh(result, material);
                done(mesh);
            });
            break;
    }
};

const robot = await loader.load('robot.urdf');
scene.add(robot);

关节控制

import { URDFLoader } from '@feng3d/urdf-loader';

const loader = new URDFLoader();
const robot = await loader.load('robot.urdf');

// 获取关节
const joint = robot.joints['joint_name'];

// 设置关节角度
joint.setJointValue(Math.PI / 2);

// 获取关节限制
console.log('关节限制:', joint.limit);

// 检查关节类型
if (joint.jointType === 'revolute') {
    console.log('这是一个旋转关节');
}

// 批量设置多个关节
robot.setJointValues({
    'joint1': Math.PI / 4,
    'joint2': Math.PI / 2,
    'joint3': 0
});

模仿关节使用

import { URDFLoader } from '@feng3d/urdf-loader';

const loader = new URDFLoader();
const robot = await loader.load('robot.urdf');

// 获取模仿关节
const mimicJoint = robot.joints['mimic_joint'] as URDFMimicJoint;

// 设置模仿参数
mimicJoint.multiplier = 2.0;  // 2倍速度
mimicJoint.offset = Math.PI / 4;  // 偏移45度

// 当被模仿关节改变时，模仿关节会自动更新
robot.joints['target_joint'].setJointValue(Math.PI / 2);

🎮 示例

项目包含完整的交互式示例，展示了URDF加载器的各种功能：

示例功能

• 🎯 模型加载: 展示不同格式的URDF模型加载
• 🎮 交互控制: 实时关节控制和动画
• 🔍 调试视图: 显示碰撞几何体和关节轴
• 📱 响应式: 适配不同屏幕尺寸
• 🎨 材质预览: 展示不同的材质和纹理
• 🔄 异步加载: 展示现代化的异步加载体验

🔧 API 文档

URDFLoader

主要的URDF加载器类。

构造函数

new URDFLoader(manager?: LoadingManager)

公共属性

• manager: 加载管理器，用于管理加载进度和错误处理
• loadMeshCb: 自定义网格加载回调函数
• parseVisual: 是否解析视觉元素，默认true
• parseCollision: 是否解析碰撞元素，默认false
• packages: 包路径配置，可以是字符串或函数
• workingPath: 工作路径，用于解析相对路径
• fetchOptions: fetch请求选项

公共方法

• load(urdf: string, onProgress?, onError?): 异步加载URDF文件，返回Promise

私有方法

• parse(content: string, workingPath?): 解析URDF内容
• defaultMeshLoader(path, manager, done): 默认网格加载器

URDFRobot

URDF机器人类，包含所有关节和链接。

公共属性

• joints: 关节对象字典
• links: 链接对象字典
• colliders: 碰撞体对象字典
• visual: 可视化对象字典
• frames: 所有帧的字典

公共方法

• getFrame(name: string | number): 获取指定名称的帧对象
• setJointValue(jointName: string, ...angle: number[]): 设置指定关节的值
• setJointValues(values: { [x: string]: number }): 批量设置多个关节的值

URDFJoint

URDF关节类。

公共属性

• jointType: 关节类型 ('revolute', 'prismatic', 'fixed', 'continuous', 'floating', 'planar')
• axis: 关节旋转轴
• limit: 关节角度限制
• jointValue: 关节当前值数组
• mimicJoints: 模仿关节列表

公共方法

• setJointValue(...values: number[]): 设置关节值
• get angle(): 获取关节角度（仅适用于单自由度关节）

URDFMimicJoint

URDF模仿关节类，继承自URDFJoint。

公共属性

• mimicJoint: 被模仿的关节名称
• offset: 关节值的偏移量
• multiplier: 关节值的乘数因子

公共方法

• updateFromMimickedJoint(...values: number[]): 根据被模仿关节的值更新当前关节

🛠️ 开发

构建

npm run build

测试

npm run test

文档生成

npm run docs

代码检查

npm run lint
npm run lintfix

📁 项目结构

@feng3d/urdf-loader/
├── src/                    # 源代码
│   ├── index.ts           # 主入口文件
│   ├── URDFLoader.ts      # URDF加载器主类
│   └── objects/           # URDF对象类
│       ├── URDFBase.ts    # 基础类
│       ├── URDFJoint.ts   # 关节类
│       ├── URDFMimicJoint.ts # 模仿关节类
│       ├── URDFLink.ts    # 链接类
│       ├── URDFRobot.ts   # 机器人类
│       ├── URDFVisual.ts  # 可视化类
│       └── URDFCollider.ts # 碰撞体类
├── examples/              # 示例代码
│   ├── src/              # 示例源代码
│   └── index.html        # 示例页面
├── test/                 # 测试文件
├── public/               # 构建输出
│   └── docs/            # 生成的文档
└── resources/           # 示例资源
    └── T12/             # 机器人模型

🔒 类型安全特性

严格的类型定义

• 完整的TypeScript支持: 所有类、方法和属性都有完整的类型定义
• 类型安全的关节操作: 关节值使用严格的number类型
• 模仿关节类型: URDFMimicJoint提供专门的模仿关节类型
• 访问修饰符: 使用public/private明确标识API边界

类型安全示例

// 类型安全的关节操作
const joint = robot.joints['arm_joint'];
joint.setJointValue(Math.PI / 2); // 只接受number类型

// 类型安全的模仿关节
const mimicJoint = robot.joints['mimic_joint'] as URDFMimicJoint;
mimicJoint.multiplier = 2.0; // 类型安全

// 类型安全的批量设置
robot.setJointValues({
    'joint1': Math.PI / 4,  // 只接受number值
    'joint2': Math.PI / 2
});

🤝 贡献

欢迎提交Issue和Pull Request！

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

开发规范

• 使用TypeScript编写代码
• 添加完整的JSDoc注释
• 使用适当的访问修饰符
• 确保类型安全
• 通过所有测试

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

感谢以下开源项目的支持：

• Three.js - 3D图形库
• TypeDoc - TypeScript文档生成器
• Vite - 构建工具

🆕 最新更新

v0.0.1 最新特性

• ✨ 类型安全提升: 所有any类型替换为具体类型
• 🔒 访问修饰符: 添加public/private访问控制
• 🔄 异步API: 现代化的Promise-based加载API
• 📖 完整注释: 详细的中文JSDoc注释
• 🛡️ 类型保护: 严格的TypeScript类型检查
• 🎯 模仿关节: 完整的URDFMimicJoint类型支持

⭐ 如果这个项目对您有帮助，请给我们一个星标！