295 lines
6.2 KiB
Markdown
295 lines
6.2 KiB
Markdown
# 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插件相同的许可证。 |