urdf模型加载器
npm install @feng3d/urdf-loaderbash
npm install @feng3d/urdf-loader
`
或者使用yarn：
`bash
yarn add @feng3d/urdf-loader
`
🎯 快速开始
$3
`typescript
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('机器人加载完成！');
`
$3
`typescript
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);
});
`
$3
`typescript
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);
`
$3
`typescript
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
});
`
$3
`typescript
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加载器的各种功能：
$3
- 🎯 模型加载: 展示不同格式的URDF模型加载
- 🎮 交互控制: 实时关节控制和动画
- 🔍 调试视图: 显示碰撞几何体和关节轴
- 📱 响应式: 适配不同屏幕尺寸
- 🎨 材质预览: 展示不同的材质和纹理
- 🔄 异步加载: 展示现代化的异步加载体验
🔧 API 文档
$3
主要的URDF加载器类。
#### 构造函数
`typescript
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): 默认网格加载器
$3
URDF机器人类，包含所有关节和链接。
#### 公共属性
- joints: 关节对象字典
- links: 链接对象字典
- colliders: 碰撞体对象字典
- visual: 可视化对象字典
- frames: 所有帧的字典
#### 公共方法
- getFrame(name: string | number): 获取指定名称的帧对象
- setJointValue(jointName: string, ...angle: number[]): 设置指定关节的值
- setJointValues(values: { [x: string]: number }): 批量设置多个关节的值
$3
URDF关节类。
#### 公共属性
- jointType: 关节类型 ('revolute', 'prismatic', 'fixed', 'continuous', 'floating', 'planar')
- axis: 关节旋转轴
- limit: 关节角度限制
- jointValue: 关节当前值数组
- mimicJoints: 模仿关节列表
#### 公共方法
- setJointValue(...values: number[]): 设置关节值
- get angle(): 获取关节角度（仅适用于单自由度关节）
$3
URDF模仿关节类，继承自URDFJoint。
#### 公共属性
- mimicJoint: 被模仿的关节名称
- offset: 关节值的偏移量
- multiplier: 关节值的乘数因子
#### 公共方法
- updateFromMimickedJoint(...values: number[]): 根据被模仿关节的值更新当前关节
🛠️ 开发
$3
`bash
npm run build
`
$3
`bash
npm run test
`
$3
`bash
npm run docs
`
$3
`bash
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/ # 机器人模型
`
🔒 类型安全特性
$3
- 完整的TypeScript支持: 所有类、方法和属性都有完整的类型定义
- 类型安全的关节操作: 关节值使用严格的number类型
- 模仿关节类型: URDFMimicJoint提供专门的模仿关节类型
- 访问修饰符: 使用public/private明确标识API边界
$3
`typescript
// 类型安全的关节操作
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！
$3
1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature`)