irg/Isometquick-server/README.md

# Isometquick Blender渲染微服务

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

## 功能特性

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

## 系统要求

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

## 快速开始

### 1. 创建输出目录

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

### 2. 安装依赖

```bash
cd Isometquick-server
pip install -r requirements.txt
```

### 3. 配置Blender路径（可选）

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

### 4. 启动服务

```bash
python start.py
```

或使用uvicorn直接启动：

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

### 5. 访问API文档

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

## API接口

### 创建渲染任务

**POST** `/render`

```json #prop_type:description="道具类型: 0=无, 1=窗, 2=拱门, 3=门"
{
  "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客户端示例

```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示例

```bash
# 创建任务（使用默认侧视图）
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
```

## 部署

### 目录准备

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

### Docker部署

```dockerfile
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服务

```ini
[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/` 目录有读写权限：

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

## 许可证

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