README_CN.md•4.3 kB
# MCP STL 3D 浮雕生成器
<div align="center">
[MCP 简介](https://modelcontextprotocol.io/introduction)
·
[Wiki](https://deepwiki.com/Bigchx/mcp_3d_relief)
</div>
本项目提供一个 MCP server，能够将 2D 图像转换为 STL 格式的 3D 浮雕模型，适用于 3D 打印或渲染。
## 功能特点
- 将任何图像转换为 3D 浮雕模型
- 可控制模型尺寸（宽度、厚度）
- 可为 3D 模型添加可选底座
- 可反转深度以获得不同的浮雕效果
- 快速处理，立即提供下载链接
## 安装
### 前提条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/#installation)
### 选项 1：本地安装
1. 克隆仓库：
```bash
git clone https://github.com/bigchx/mcp_3d_relief.git
cd mcp_3d_relief
```
2. 安装依赖：
```bash
uv pip sync requirements.txt
```
3. 运行/调试服务器：
```bash
mcp run server.py
mcp dev server.py
```
## 使用方法
### JSON 配置
```json
{
"mcpServers": {
"mcp_3d_relief": {
"command": "uv",
"args": ["--directory", "{fill_in_your_path_here}", "run", "server.py"]
}
}
}
```
### MCP 工具参数
- `image_path`：要转换的图像本地路径或 URL
- `model_width`：3D 模型的宽度（毫米，默认：50.0）
- `model_thickness`：3D 模型的最大厚度/高度（毫米，默认：5.0）
- `base_thickness`：底座厚度（毫米，默认：2.0）
- `skip_depth`：是否直接使用图像或生成深度图（默认：true）
- `invert_depth`：是否反转浮雕（明亮区域变低而不是高，默认：false）
- `detail_level`：控制处理图像的分辨率（默认：1.0）。当 detail_level = 1.0 时，图像以 320px 分辨率处理，生成的 STL 文件通常在 100MB 以内。较高的值可以提高细节质量，但会显著增加处理时间和 STL 文件大小。例如，将 detail_level 值加倍可能会使文件大小增加 4 倍或更多，请谨慎使用。
### 响应
MCP 工具返回的 JSON 响应包含：
```json
{
"status": "success",
"depth_map_path": "path/to/yourimage_depth_map.png",
"stl_path": "path/to/yourimage.stl"
}
```
大语言模型可通过提供的 URL 访问生成的文件。
### 命令行
您也可以直接从命令行使用脚本：
```bash
python3 relief.py path/to/your/image.jpg
```
### 外部深度图生成
为获得更高质量的深度图，您可以使用外部深度图生成服务，如 [Depth-Anything-V2](https://huggingface.co/spaces/depth-anything/Depth-Anything-V2)。该服务可以生成更准确的深度图，然后您可以将其用于本项目：
1. 访问 [https://huggingface.co/spaces/depth-anything/Depth-Anything-V2](https://huggingface.co/spaces/depth-anything/Depth-Anything-V2)
2. 上传您的图像以生成深度图
3. 下载生成的深度图
4. 将此深度图与我们的转换器一起使用，设置 `skip_depth=false`
这种方法可以提供更好的 3D 浮雕模型，特别是对于复杂图像。
## 工作原理
1. 处理图像创建深度图（较暗像素 = 较低，较亮像素 = 较高）
2. 将深度图转换为带有三角形面的 3D 网格
3. 在模型底部添加底座
4. 将模型保存为 STL 文件
## 合作伙伴
<div style="display: flex; justify-content: center; align-items: center; gap: 20px; margin: 30px 0;">
<div style="flex: 1; text-align: center; padding: 15px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); transition: all 0.2s ease-in-out; max-width: 300px; hover:transform: translateY(-5px); hover:box-shadow: 0 6px 16px rgba(0,0,0,0.15);">
<a href="https://www.voxeldance.com/" style="display: block; height: 100%;">
<img src="images/voxeldance.png" alt="voxeldance" style="max-width: 100%; height: auto; object-fit: contain; transition: opacity 0.2s ease-in-out;">
</a>
</div>
<div style="flex: 1; text-align: center; padding: 15px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); transition: all 0.2s ease-in-out; max-width: 300px; hover:transform: translateY(-5px); hover:box-shadow: 0 6px 16px rgba(0,0,0,0.15);">
<a href="https://www.3dzyk.cn/" style="display: block; height: 100%;">
<img src="images/3dzyk.png" alt="3dzyk" style="max-width: 100%; height: auto; object-fit: contain; transition: opacity 0.2s ease-in-out;">
</a>
</div>
</div>