mcp_3d_relief

🚀 MCP STL 3D浮雕生成器

本项目提供了一个MCP服务器，可将二维图像转换为STL格式的3D浮雕模型，适用于3D打印或渲染。

🚀 快速开始

MCP STL 3D浮雕生成器是一个强大的工具，能轻松将二维图像转换为可用于3D打印或渲染的STL格式3D浮雕模型。以下是快速开始使用该项目的相关介绍。

✨ 主要特性

• 可将任意图像转换为3D浮雕模型。
• 能够控制模型的尺寸（宽度、厚度）。
• 可为3D模型添加可选的底座。
• 可反转深度以实现不同的浮雕效果。
• 处理速度快，并提供即时下载链接。

📦 安装指南

前提条件

• Python 3.10及以上版本。
• uv

选项1：本地安装

1. 克隆仓库：

git clone https://github.com/bigchx/mcp_3d_relief.git
cd mcp_3d_relief

2. 安装依赖：

uv pip sync requirements.txt

3. 运行/检查服务器：

mcp run server.py
mcp dev server.py

💻 使用示例

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时，图像以320像素分辨率进行处理，生成的STL文件通常小于100MB。值越高，细节质量越好，但处理时间和STL文件大小会显著增加。例如，将detail_level翻倍，文件大小可能会增加4倍或更多，使用时需谨慎。

响应

MCP工具返回的JSON响应如下：

{
  "status": "success",
  "depth_map_path": "path/to/yourimage_depth_map.png",
  "stl_path": "path/to/yourimage.stl"
}

大语言模型（LLMs）可以通过提供的URL从该MCP服务器访问生成的文件。

命令行方式

你也可以直接从命令行使用脚本从图像生成浮雕模型：

python3 relief.py path/to/your/image.jpg

外部深度图生成

为了获得更高质量的深度图，你可以使用Depth-Anything-V2等外部深度图生成服务。该服务可以生成更准确的深度图，然后你可以在本项目中使用：

1. 访问https://huggingface.co/spaces/depth-anything/Depth-Anything-V2。
2. 上传你的图像以生成深度图。
3. 下载生成的深度图。
4. 通过设置skip_depth=false，将此深度图与我们的转换器一起使用。 这种方法可以提供更好的3D浮雕模型，尤其适用于复杂图像。

📚 详细文档

工作原理

1. 处理图像以创建深度图（较暗像素表示较低，较亮像素表示较高）。
2. 将深度图转换为带有三角形面的3D网格。
3. 在模型底部添加底座。
4. 将模型保存为STL文件。

我们的合作伙伴

</a>

</a>