npm package: @feng3d/urdf-loader
Description: urdf模型加载器
Author: feng
Latest version: 0.0.1

# 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

## 📦 安装

```bash
npm install @feng3d/urdf-loader
```

或者使用yarn：

```bash
yarn add @feng3d/urdf-loader
```

## 🎯 快速开始

### 基本使用

```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('机器人加载完成！');
```

### 使用Promise方式

```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);
  });
```

### 自定义材质加载

```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);
```

### 关节控制

```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
});
```

### 模仿关节使用

```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加载器的各种功能：

### 示例功能

- **🎯 模型加载**: 展示不同格式的URDF模型加载
- **🎮 交互控制**: 实时关节控制和动画
- **🔍 调试视图**: 显示碰撞几何体和关节轴
- **📱 响应式**: 适配不同屏幕尺寸
- **🎨 材质预览**: 展示不同的材质和纹理
- **🔄 异步加载**: 展示现代化的异步加载体验

## 🔧 API 文档

### URDFLoader

主要的URDF加载器类。

#### 构造函数

```typescript
new URDFLoader(manager?: LoadingManager)
```

#### 公共属性

- `manager`: 加载管理器，用于管理加载进度和错误处理
- `loadMeshCb`: 自定义网格加载回调函数
- `parseVisual`: 是否解析视觉元素，默认true
- `parseCollision`: 是否解析碰撞元素，默认false
- `packages`: 包路径配置，可以是字符串或函数
- `workingPath`: 工作路径，用于解析相对路径
- `fetchOptions`: fetch请求选项

#### 公共方法

- `load(urdf: string, onProgress?, onError?)`: 异步加载URDF文件，返回Promise<URDFRobot>

#### 私有方法

- `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[])`: 根据被模仿关节的值更新当前关节

## 🛠️ 开发

### 构建

```bash
npm run build
```

### 测试

```bash
npm run test
```

### 文档生成

```bash
npm run docs
```

### 代码检查

```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/             # 机器人模型
```

## 🔒 类型安全特性

### 严格的类型定义

- **完整的TypeScript支持**: 所有类、方法和属性都有完整的类型定义
- **类型安全的关节操作**: 关节值使用严格的number类型
- **模仿关节类型**: URDFMimicJoint提供专门的模仿关节类型
- **访问修饰符**: 使用public/private明确标识API边界

### 类型安全示例

```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！

### 贡献指南

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](LICENSE) 文件了解详情。

## 🙏 致谢

感谢以下开源项目的支持：

- [Three.js](https://threejs.org/) - 3D图形库
- [TypeDoc](https://typedoc.org/) - TypeScript文档生成器
- [Vite](https://vitejs.dev/) - 构建工具

## 🆕 最新更新

### v0.0.1 最新特性

- ✨ **类型安全提升**: 所有any类型替换为具体类型
- 🔒 **访问修饰符**: 添加public/private访问控制
- 🔄 **异步API**: 现代化的Promise-based加载API
- 📖 **完整注释**: 详细的中文JSDoc注释
- 🛡️ **类型保护**: 严格的TypeScript类型检查
- 🎯 **模仿关节**: 完整的URDFMimicJoint类型支持

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！