irg/Isometquick-server

Isometquick Blender渲染微服务

基于FastAPI的Blender等轴测房间渲染API服务，专为Linux服务器环境设计。

功能特性

• 🏠 等轴测房间渲染: 支持自定义房间尺寸
• 📷 多视角渲染: 正视图和侧视图
• 🎨 多渲染引擎: 工作台、EEVEE Next、Cycles
• 🚀 异步处理: 后台渲染任务
• 📊 任务管理: 任务状态查询和文件下载
• 🔍 API文档: 自动生成的Swagger文档

系统要求

• Python 3.8+
• Blender 4.3+
• Linux服务器环境
• Isometquick插件已安装
• 确保 /data/Isometquick/ 目录存在且有写入权限

快速开始

1. 创建输出目录

sudo mkdir -p /data/Isometquick/
sudo chown $USER:$USER /data/Isometquick/
sudo chmod 755 /data/Isometquick/

2. 安装依赖

cd Isometquick-server
pip install -r requirements.txt

3. 配置Blender路径（可选）

export BLENDER_PATH="/usr/local/bin/blender"

4. 启动服务

python start.py

或使用uvicorn直接启动：

uvicorn main:app --host 0.0.0.0 --port 8003

5. 访问API文档

打开浏览器访问：http://localhost:8003/docs

API接口

创建渲染任务

POST /render

{
  "room": {
    "length": 4.0,
    "width": 4.0,
    "height": 3.0,
    "prop_type":0,
  },
  "camera": {
    "height": 1.3,
    "view_type": 2,
    "rotation_angle": 45.0
  },
  "render": {
    "resolution_x": 1080,
    "resolution_y": 2400,
    "engine": "workbench"
  }
}

查询任务状态

GET /render/{task_id}

下载渲染结果

GET /render/{task_id}/download

注意: 渲染图片保存在 /data/Isometquick/ 目录下，文件名格式为 render_{task_id}.png

删除任务

DELETE /render/{task_id}

参数说明

房间尺寸 (room)

• length: 房间长度(X轴)，默认4.0米
• width: 房间宽度(Y轴)，默认4.0米
• height: 房间高度(Z轴)，默认3.0米

摄像机设置 (camera)

• height: 摄像机垂直高度，默认1.3米
• view_type: 视图类型，1=正视图，2=侧视图（默认侧视图）
• rotation_angle: 摄像机旋转角度（仅侧视图），默认45度

摄像机位置计算

正视图 (view_type=1):

• 位置: (0, -(width/2-1), height)
• 旋转: (90°, 0°, 0°)

侧视图 (view_type=2) - 默认:

• 位置: ((length/2-1), -(width/2-1), height)
• 旋转: (90°, 0°, rotation_angle)

渲染设置 (render)

• resolution_x: 渲染宽度，默认1080px
• resolution_y: 渲染高度，默认2400px
• engine: 渲染引擎，支持workbench/eevee/cycles

文件存储

• 输出目录: /data/Isometquick/
• 文件命名: render_{task_id}.png
• 文件权限: 确保服务进程对该目录有读写权限
• 清理策略: 24小时后自动清理旧文件

使用示例

Python客户端示例

import requests
import time

# 创建渲染任务（使用默认侧视图）
response = requests.post("http://localhost:8003/render", json={
    "room": {
        "length": 5.0,
        "width": 4.0,
        "height": 3.5
    },
    "camera": {
        "height": 1.5,
        "view_type": 2,
        "rotation_angle": 30.0
    },
    "render": {
        "resolution_x": 1920,
        "resolution_y": 1080,
        "engine": "workbench"
    }
})

task_id = response.json()["task_id"]

# 轮询任务状态
while True:
    status_response = requests.get(f"http://localhost:8003/render/{task_id}")
    status = status_response.json()["status"]
    
    if status == "completed":
        # 下载结果
        download_response = requests.get(f"http://localhost:8003/render/{task_id}/download")
        with open(f"render_{task_id}.png", "wb") as f:
            f.write(download_response.content)
        break
    elif status == "failed":
        print("渲染失败")
        break
    
    time.sleep(2)

curl示例

# 创建任务（使用默认侧视图）
curl -X POST "http://localhost:8003/render" \
     -H "Content-Type: application/json" \
     -d '{
       "room": {"length": 4.0, "width": 4.0, "height": 3.0},
       "camera": {"height": 1.3, "view_type": 2, "rotation_angle": 45.0},
       "render": {"resolution_x": 1080, "resolution_y": 2400, "engine": "workbench"}
     }'

# 查询状态
curl "http://localhost:8003/render/{task_id}"

# 下载结果
curl "http://localhost:8003/render/{task_id}/download" -o render.png

部署

目录准备

# 创建输出目录
sudo mkdir -p /data/Isometquick/
sudo chown www-data:www-data /data/Isometquick/  # 或适当的用户
sudo chmod 755 /data/Isometquick/

Docker部署

FROM python:3.9-slim

# 安装Blender
RUN apt-get update && apt-get install -y blender

# 创建输出目录
RUN mkdir -p /data/Isometquick/

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

# 确保输出目录权限
RUN chmod 755 /data/Isometquick/

EXPOSE 8003
CMD ["python", "start.py"]

systemd服务

[Unit]
Description=Isometquick Blender Render Service
After=network.target

[Service]
Type=simple
User=blender
WorkingDirectory=/opt/isometquick-server
ExecStart=/usr/bin/python3 start.py
Restart=always
RestartSec=3

# 确保有访问输出目录的权限
ReadWritePaths=/data/Isometquick/

[Install]
WantedBy=multi-user.target

性能优化

• 调整 MAX_CONCURRENT_RENDERS 控制并发渲染数量
• 使用工作台引擎获得最快渲染速度
• 定期清理旧的渲染文件
• 考虑使用Redis存储任务状态（生产环境）
• 监控 /data/Isometquick/ 目录磁盘使用情况

故障排除

Blender未找到

确保Blender已安装并在系统PATH中，或设置BLENDER_PATH环境变量。

插件未加载

确保Isometquick插件已正确安装在Blender中。

渲染超时

调整BLENDER_TIMEOUT配置或优化渲染参数。

文件权限错误

确保服务进程对 /data/Isometquick/ 目录有读写权限：

sudo chown -R $SERVICE_USER:$SERVICE_GROUP /data/Isometquick/
sudo chmod -R 755 /data/Isometquick/

许可证

与原Isometquick插件相同的许可证。