prompt.md

# 3D建模与模型处理技能 - 调用指南与参数说明

## 目录
1. [通用调用规范](#通用调用规范)
2. [功能调用步骤详解](#功能调用步骤详解)
3. [完整参数说明](#完整参数说明)
4. [输入输出格式规范](#输入输出格式规范)
5. [3D格式编码说明](#3d格式编码说明)
6. [错误处理与异常说明](#错误处理与异常说明)
7. [使用注意事项](#使用注意事项)

---

## 通用调用规范

### 技能入口函数

所有功能通过统一的`execute`函数调用：

```python
def execute(params: Dict[str, Any]) -> Dict[str, Any]
```

### 标准返回格式

所有操作返回统一的结果结构：

```python
{
    "success": bool,           # 操作是否成功
    "message": str,            # 操作结果描述
    "data": Dict[str, Any],    # 操作返回数据
    "error": str | None,       # 错误信息（失败时）
    "output_files": List[str]  # 生成的文件路径列表
}
```

### 操作类型枚举

| operation值 | 功能模块 |
|------------|---------|
| `generate_primitive` | 基础3D几何体生成 |
| `transform` | 3D模型编辑-变换 |
| `boolean` | 3D模型编辑-布尔运算 |
| `material` | 材质与纹理处理 |
| `render` | 3D场景渲染 |
| `convert_format` | 3D格式转换 |
| `parametric` | 参数化建模 |
| `print_preprocess` | 3D打印预处理 |
| `measure` | 3D模型测量 |
| `optimize` | 模型优化 |
| `batch_process` | 批量3D模型处理 |
| `import_export` | 3D模型导入导出 |
| `visualize` | 3D模型可视化预览 |

---

## 功能调用步骤详解

### 1. 基础3D几何体生成

**调用步骤**：
1. 指定`operation = "generate_primitive"`
2. 选择几何体类型`primitive_type`
3. 设置尺寸参数
4. （可选）设置位置、旋转参数
5. （可选）指定输出文件路径

**调用示例**：
```python
result = execute({
    "operation": "generate_primitive",
    "primitive_type": "box",
    "extents": [100, 50, 30],
    "position": [0, 0, 0],
    "rotation": [0, 0, 0],
    "output_file": "my_box.stl"
})
```

---

### 2. 3D模型编辑 - 变换

**调用步骤**：
1. 指定`operation = "transform"`
2. 提供要编辑的模型ID`mesh_id`
3. 设置变换参数（平移/旋转/缩放）
4. （可选）保存结果到文件

**调用示例**：
```python
result = execute({
    "operation": "transform",
    "mesh_id": "existing_mesh_id",
    "translation": [10, 20, 30],
    "rotation": [45, 0, 90],
    "scale": 1.5,
    "degrees": True,
    "output_file": "transformed_model.stl"
})
```

---

### 3. 3D模型编辑 - 布尔运算

**调用步骤**：
1. 指定`operation = "boolean"`
2. 提供两个模型ID：`mesh1_id`和`mesh2_id`
3. 指定布尔运算类型`boolean_type`
4. （可选）保存结果到文件

**调用示例**：
```python
result = execute({
    "operation": "boolean",
    "mesh1_id": "cube_id",
    "mesh2_id": "cylinder_id",
    "boolean_type": "difference",
    "output_file": "cube_with_hole.stl"
})
```

---

### 4. 材质与纹理处理

**调用步骤**：
1. 指定`operation = "material"`
2. 提供模型ID`mesh_id`
3. 指定材质操作类型`material_operation`
4. 设置相应的材质参数

**调用示例**：
```python
# 设置顶点颜色
result = execute({
    "operation": "material",
    "mesh_id": "model_id",
    "material_operation": "set_color",
    "color": [100, 150, 200, 255]
})

# UV展开
result = execute({
    "operation": "material",
    "mesh_id": "model_id",
    "material_operation": "uv_unwrap"
})
```

---

### 5. 3D场景渲染

**调用步骤**：
1. 指定`operation = "render"`
2. 提供模型ID`mesh_id`
3. 设置渲染参数（颜色、相机、光照）
4. 指定输出图片路径

**调用示例**：
```python
result = execute({
    "operation": "render",
    "mesh_id": "model_id",
    "color": "#4A90D9",
    "show_edges": True,
    "edge_color": "black",
    "background_color": "white",
    "azimuth": 45,
    "elevation": 30,
    "zoom": 1.2,
    "window_size": [1920, 1080],
    "output_image": "render.png"
})
```

---

### 6. 3D格式转换

**调用步骤**：
1. 指定`operation = "convert_format"`
2. 提供输入文件路径`input_file`
3. 提供输出文件路径`output_file`
4. 系统自动识别格式并转换

**调用示例**：
```python
result = execute({
    "operation": "convert_format",
    "input_file": "input_model.stl",
    "output_file": "output_model.obj"
})
```

---

### 7. 参数化建模

**调用步骤**：
1. 指定`operation = "parametric"`
2. 选择建模类型`model_type`
3. 提供相应的几何参数
4. （可选）保存结果到文件

**调用示例**：
```python
# 拉伸建模
result = execute({
    "operation": "parametric",
    "model_type": "extrusion",
    "polygon_points": [[0,0], [1,0], [1,1], [0,1]],
    "height": 2.0,
    "output_file": "extruded.stl"
})

# 旋转建模
result = execute({
    "operation": "parametric",
    "model_type": "revolution",
    "profile_points": [[0,0], [1,0], [1,1]],
    "angle": 360,
    "segments": 64
})
```

---

### 8. 3D打印预处理

**调用步骤**：
1. 指定`operation = "print_preprocess"`
2. 提供模型ID`mesh_id`
3. 选择预处理操作`preprocess_operation`
4. 设置相应参数

**调用示例**：
```python
# 模型修复
result = execute({
    "operation": "print_preprocess",
    "mesh_id": "model_id",
    "preprocess_operation": "repair",
    "output_file": "repaired.stl"
})

# 壁厚检查
result = execute({
    "operation": "print_preprocess",
    "mesh_id": "model_id",
    "preprocess_operation": "wall_thickness_check",
    "min_thickness": 1.2
})

# 打印参数计算
result = execute({
    "operation": "print_preprocess",
    "mesh_id": "model_id",
    "preprocess_operation": "print_calculation",
    "material_density": 1.04,
    "infill_percent": 20
})
```

---

### 9. 3D模型测量

**调用步骤**：
1. 指定`operation = "measure"`
2. 提供模型ID`mesh_id`
3. （可选）指定测量选项
4. 获取完整测量结果

**调用示例**：
```python
result = execute({
    "operation": "measure",
    "mesh_id": "model_id",
    "calculate_bounding_box": True
})

# 测量结果包含：
# - 尺寸（宽/深/高）
# - 体积
# - 表面积
# - 重心
# - 顶点/面/边计数
# - 水密性检查
```

---

### 10. 模型优化

**调用步骤**：
1. 指定`operation = "optimize"`
2. 提供模型ID`mesh_id`
3. 选择优化类型`optimization_type`
4. 设置优化参数
5. （可选）保存结果

**调用示例**：
```python
# 网格减面
result = execute({
    "operation": "optimize",
    "mesh_id": "high_poly_model",
    "optimization_type": "decimate",
    "target_ratio": 0.5,
    "output_file": "optimized.stl"
})

# 平滑处理
result = execute({
    "operation": "optimize",
    "mesh_id": "model_id",
    "optimization_type": "smooth",
    "iterations": 15
})

# 孔洞填充
result = execute({
    "operation": "optimize",
    "mesh_id": "model_id",
    "optimization_type": "fill_holes"
})
```

---

### 11. 批量3D模型处理

**调用步骤**：
1. 指定`operation = "batch_process"`
2. 提供输入目录`input_directory`
3. 选择批量操作`batch_operation`
4. 设置输出目录和参数

**调用示例**：
```python
# 批量格式转换
result = execute({
    "operation": "batch_process",
    "batch_operation": "convert_format",
    "input_directory": "./input_models",
    "output_directory": "./output_models",
    "target_format": ".stl"
})

# 批量优化
result = execute({
    "operation": "batch_process",
    "batch_operation": "optimize",
    "input_directory": "./high_poly",
    "output_directory": "./optimized"
})
```

---

### 12. 3D模型导入导出

**调用步骤**：
1. 指定`operation = "import_export"`
2. 选择操作类型`io_operation`（import/export）
3. 提供文件路径和模型ID

**调用示例**：
```python
# 导入模型
result = execute({
    "operation": "import_export",
    "io_operation": "import",
    "input_file": "external_model.stl"
})

# 导出模型
result = execute({
    "operation": "import_export",
    "io_operation": "export",
    "mesh_id": "model_id",
    "output_file": "exported_model.obj"
})
```

---

### 13. 3D模型可视化预览

**调用步骤**：
1. 指定`operation = "visualize"`
2. 提供模型ID`mesh_id`
3. 设置显示参数
4. （可选）截图保存

**调用示例**：
```python
result = execute({
    "operation": "visualize",
    "mesh_id": "model_id",
    "color": "lightblue",
    "show_edges": True,
    "show_vertices": False,
    "style": "surface",
    "background": "white",
    "title": "3D Model Preview",
    "screenshot_file": "preview.png",
    "headless": False
})
```

---

## 完整参数说明

### 通用参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `operation` | string | 必填 | 见操作类型枚举 | 要执行的操作类型 |
| `mesh_id` | string | None | 有效模型ID | 操作目标模型的唯一标识 |
| `output_file` | string | None | 有效文件路径 | 输出模型文件路径 |

---

### 几何体生成参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `primitive_type` | string | "box" | box/sphere/cylinder/cone/torus/icosphere/tetrahedron/octahedron/icosahedron | 几何体类型 |
| `size` | float | 1.0 | >0 | 基础尺寸（半径/边长） |
| `extents` | list[3] | [size, size, size] | 正数数组 | 立方体长宽高 |
| `position` | list[3] | [0, 0, 0] | 任意数值 | 模型位置坐标 |
| `rotation` | list[3] | [0, 0, 0] | 0-360 | 欧拉旋转角 |
| `segments` | int | 32 | 4-256 | 圆周分段数 |
| `subdivisions` | int | 3 | 1-6 | 球体细分级别 |
| `height` | float | size*2 | >0 | 圆柱/圆锥高度 |
| `major_radius` | float | size | >0 | 圆环主半径 |
| `minor_radius` | float | size*0.3 | >0 | 圆环次半径 |

---

### 变换参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `translation` | list[3] | None | 任意数值 | XYZ平移量 |
| `rotation` | list[3] | None | 任意数值 | 欧拉旋转角 |
| `scale` | float/list[3] | None | >0 | 缩放因子 |
| `degrees` | bool | True | True/False | 旋转角是否为角度 |

---

### 布尔运算参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `mesh1_id` | string | 必填 | 有效模型ID | 第一个运算对象 |
| `mesh2_id` | string | 必填 | 有效模型ID | 第二个运算对象 |
| `boolean_type` | string | "union" | union/intersection/difference | 布尔运算类型 |

---

### 渲染参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `color` | string/list | "lightblue" | 颜色名/HEX/RGB | 模型颜色 |
| `show_edges` | bool | False | True/False | 是否显示边线 |
| `edge_color` | string | "black" | 颜色名 | 边线颜色 |
| `opacity` | float | 1.0 | 0-1 | 透明度 |
| `background_color` | string | "white" | 颜色名 | 背景颜色 |
| `camera_position` | list | None | 相机坐标 | 自定义相机位置 |
| `azimuth` | float | 45 | 0-360 | 方位角 |
| `elevation` | float | 30 | -90-90 | 仰角 |
| `zoom` | float | 1.0 | >0 | 缩放系数 |
| `window_size` | list[2] | [1920, 1080] | 正整数 | 输出分辨率 |
| `output_image` | string | "render_output.png" | 有效路径 | 输出图片路径 |
| `off_screen` | bool | True | True/False | 离线渲染模式 |
| `enable_lighting` | bool | True | True/False | 启用光照 |
| `show_axes` | bool | True | True/False | 显示坐标轴 |

---

### 格式转换参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `input_file` | string | 必填 | 有效文件路径 | 输入模型文件 |
| `output_file` | string | 必填 | 有效文件路径 | 输出模型文件 |

---

### 参数化建模参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `model_type` | string | "extrusion" | extrusion/revolution/sweep | 建模类型 |
| `polygon_points` | list[N][2] | 正方形 | 2D点数组 | 拉伸截面轮廓 |
| `profile_points` | list[N][2] | 矩形 | 2D点数组 | 旋转轮廓线 |
| `height` | float | 1.0 | >0 | 拉伸高度 |
| `angle` | float | 360 | 0-360 | 旋转角度 |
| `segments` | int | 32 | 4-256 | 旋转分段数 |

---

### 3D打印预处理参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `preprocess_operation` | string | "repair" | repair/wall_thickness_check/orient_for_printing/slice_preview/print_calculation | 预处理操作 |
| `min_thickness` | float | 1.0 | >0 | 最小壁厚要求 |
| `layer_height` | float | 0.2 | 0.05-0.3 | 打印层厚 |
| `material_density` | float | 1.04 | >0 | 材料密度(g/cm³) |
| `infill_percent` | int | 20 | 0-100 | 填充百分比 |

---

### 模型优化参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `optimization_type` | string | "decimate" | decimate/smooth/fill_holes/fix_normals/remove_duplicates | 优化类型 |
| `target_ratio` | float | 0.5 | 0-1 | 目标面数比例 |
| `iterations` | int | 10 | 1-100 | 平滑迭代次数 |

---

### 批量处理参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `batch_operation` | string | "convert_format" | convert_format/optimize/repair | 批量操作类型 |
| `input_directory` | string | 必填 | 有效目录路径 | 输入目录 |
| `output_directory` | string | "./batch_output" | 有效目录路径 | 输出目录 |
| `target_format` | string | ".stl" | 支持的格式扩展名 | 目标格式 |

---

### 可视化参数

| 参数名 | 类型 | 默认值 | 取值范围 | 说明 |
|--------|------|--------|---------|------|
| `color` | string | "lightblue" | 颜色名 | 模型颜色 |
| `show_edges` | bool | True | True/False | 显示边线 |
| `show_vertices` | bool | False | True/False | 显示顶点 |
| `style` | string | "surface" | surface/wireframe/points | 显示样式 |
| `background` | string | "white" | 颜色名 | 背景颜色 |
| `title` | string | "3D Model Visualization" | 任意文本 | 窗口标题 |
| `screenshot_file` | string | None | 有效路径 | 截图保存路径 |
| `headless` | bool | False | True/False | 无头模式 |

---

## 输入输出格式规范

### 输入格式要求

1. **文件路径**：
   - 支持绝对路径和相对路径
   - 路径分隔符使用正斜杠(/)或双反斜杠(\\)
   - 避免路径中包含中文和特殊字符

2. **模型文件**：
   - 确保文件存在且可读
   - 文件格式必须在支持列表中
   - 建议文件大小不超过500MB

3. **参数格式**：
   - 所有数值参数使用浮点数或整数
   - 坐标使用右手坐标系
   - 角度默认使用角度制(0-360)

### 输出格式规范

1. **成功响应**：
```json
{
    "success": true,
    "message": "操作成功描述",
    "data": {
        "具体返回数据": "值"
    },
    "error": null,
    "output_files": ["生成的文件路径"]
}
```

2. **失败响应**：
```json
{
    "success": false,
    "message": "操作失败描述",
    "data": {},
    "error": "具体错误信息",
    "output_files": []
}
```

3. **文件输出**：
   - 输出文件自动创建目录
   - 同名文件自动覆盖
   - 输出格式由文件扩展名自动识别

---

## 3D格式编码说明

### STL格式
- **二进制STL**：推荐使用，文件小，读取快
- **ASCII STL**：可读性好，文件较大
- **单位**：无内置单位，建议使用毫米(mm)

### OBJ格式
- 支持材质文件(.mtl)
- 支持UV纹理坐标
- 支持顶点法线
- 纯文本格式，可直接编辑

### PLY格式
- 支持顶点颜色
- 支持自定义属性
- ASCII/二进制双模式

### GLB/GLTF格式
- GLB：二进制单文件，推荐
- GLTF：JSON+外部资源
- 支持PBR材质
- 支持动画和骨骼

---

## 错误处理与异常说明

### 错误代码说明

| 错误类型 | 常见原因 | 解决方案 |
|---------|---------|---------|
| `Missing dependency` | 缺少依赖库 | 安装trimesh/pyvista等依赖 |
| `Invalid mesh_id` | 模型ID不存在 | 检查模型是否已导入或生成 |
| `File not found` | 输入文件不存在 | 检查文件路径是否正确 |
| `Invalid operation` | 操作类型错误 | 检查operation参数值 |
| `Boolean operation failed` | 布尔运算失败 | 确保模型是水密的，尝试修复后重试 |
| `Format not supported` | 不支持的格式 | 使用支持的文件格式 |
| `Out of memory` | 内存不足 | 简化模型或增加可用内存 |

### 异常处理最佳实践

1. **始终检查返回值**：
```python
result = execute(params)
if not result["success"]:
    print(f"错误: {result['error']}")
    # 进行错误处理
```

2. **布尔运算前检查水密性**：
```python
# 先测量检查
measure = execute({"operation": "measure", "mesh_id": mesh_id})
if not measure["data"]["is_watertight"]:
    # 先修复模型
    execute({"operation": "optimize", "optimization_type": "fill_holes"})
```

3. **大模型处理建议**：
   - 先进行减面优化
   - 增加系统可用内存
   - 使用64位Python环境

---

## 使用注意事项

### 性能优化建议

1. **模型复杂度控制**：
   - 常规使用：1万-10万面
   - 布尔运算：建议5万面以下
   - 实时渲染：建议10万面以下

2. **内存管理**：
   - 处理完及时清理缓存
   - 避免同时加载过多大模型
   - 定期调用`clear_cache()`

3. **批量处理**：
   - 控制单次批量文件数
   - 大文件建议逐个处理
   - 监控内存使用情况

### 3D打印注意事项

1. **模型质量要求**：
   - 必须是水密模型
   - 法线方向统一朝外
   - 最小壁厚≥1.2mm
   - 避免非流形几何

2. **尺寸单位**：
   - 建议统一使用毫米(mm)
   - 导出前确认尺寸正确
   - 打印前再次测量验证

### 常见问题解决

1. **布尔运算失败**：
   - 检查模型是否水密
   - 尝试先修复模型
   - 简化模型后重试
   - 确保两个模型有重叠

2. **渲染花屏/异常**：
   - 检查法线方向
   - 尝试修复法向
   - 更新显卡驱动

3. **导出文件无法打开**：
   - 检查文件扩展名是否正确
   - 尝试转换为其他格式
   - 使用第三方软件验证

---

## 高级技巧

1. **工作流组合**：
   - 生成 → 布尔 → 优化 → 修复 → 测量 → 导出
   - 多个操作可以链式调用

2. **参数化设计**：
   - 使用循环生成变体
   - 参数扫描优化设计
   - 批量生成设计方案

3. **自动化脚本**：
   - 结合Python循环实现批处理
   - 集成到CI/CD流水线
   - 自定义工作流脚本

---

**本指南涵盖3D建模与模型处理技能的所有功能调用方法。如有疑问，请参考SKILL.md或联系技术支持。**