终末地拼图解谜工具 API

✨ 功能特性

• 截图智能解析：上传游戏截图，自动识别网格、障碍物、锁定方块、拼图块和行列颜色约束
  • 使用基于 YOLO11 训练的模型进行区域检测和网格识别
  • 使用 OpenCV 进行需求解析和拼图块识别
• CSP 自动求解：使用 Google OR-Tools CP-SAT 求解器自动找出解法

🛠️ 技术栈

• FastAPI - 高性能异步 Web 框架
• Google OR-Tools - CP-SAT 约束求解器
• ONNX Runtime - 模型推理引擎
• OpenCV - 图像处理
• uv - Python 包管理器

📡 API 接口

健康检查

GET /

响应

{
  "status": "ok"
}

解析拼图截图

POST /parse
Content-Type: multipart/form-data

请求体

参数	类型	描述
file	File	拼图截图图片文件

响应

返回解析后的 Puzzle 对象。

错误码

状态码	描述
400	图片解码失败或解析失败
415	不支持的媒体类型（非图片文件）
500	服务器内部错误

求解拼图

POST /solve
Content-Type: application/json

请求体

Puzzle 对象，包含拼图数据。

响应

返回 PlacedPiece 数组，表示每个拼图块的放置位置。

错误码

状态码	描述
400	求解失败（无解或约束冲突）
500	服务器内部错误

📦 数据模型

Puzzle

拼图数据结构，用作解析输出和求解输入。

{
  "rows": 5,
  "cols": 5,
  "obstacles": [
    [
      0,
      0
    ],
    [
      1,
      2
    ]
  ],
  "lockedBlocks": [
    {
      "coord": [
        2,
        3
      ],
      "color": 1
    }
  ],
  "rowRequirements": [
    {
      "0": 2,
      "1": 3
    },
    {
      "0": 1,
      "1": 4
    }
  ],
  "colRequirements": [
    {
      "0": 3,
      "1": 2
    }
  ],
  "pieces": [
    {
      "id": 0,
      "color": 1,
      "shape": [
        [
          0,
          0
        ],
        [
          0,
          1
        ],
        [
          1,
          0
        ]
      ]
    }
  ]
}

字段	类型	描述
rows	int	网格行数
cols	int	网格列数
obstacles	list[Coord]	障碍物坐标列表
lockedBlocks	list[LockedBlock]	锁定方块列表
rowRequirements	list[dict]	每行各颜色需求数量
colRequirements	list[dict]	每列各颜色需求数量
pieces	list[Piece]	可用拼图块列表

Piece

拼图块定义。

字段	类型	描述
id	int	拼图块唯一标识
color	int	颜色 ID
shape	list[Coord]	形状坐标偏移列表

LockedBlock

锁定方块，预先放置在网格上的固定颜色方块。

字段	类型	描述
coord	Coord	坐标位置 (row, col)
color	int	颜色 ID

PlacedPiece

放置结果，表示拼图块在网格上的位置。

字段	类型	描述
id	int	对应拼图块的 ID
anchor	Coord	锚点坐标 (row, col)
shape	list[Coord]	相对于锚点的形状坐标

🚀 快速开始

前置要求

• Python 3.12+
• uv（Python 包管理器）

本地开发

# 安装依赖
uv sync

# 启动开发服务器（端口 8000）
uv run fastapi dev

API 文档访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Docker 部署

# 构建镜像
docker build -t ak-endfield-puzzle-api .

# 运行容器（端口 9000）
docker run -p 9000:9000 ak-endfield-puzzle-api

📁 项目结构

ak-endfield-puzzle-api/
├── main.py              # FastAPI 应用入口
├── schemas.py           # Pydantic 数据模型
├── solver/
│   └── solve.py         # OR-Tools CP-SAT 求解器
├── parser/
│   ├── parse.py         # 图像解析主模块
│   ├── detector/        # 区域检测器
│   ├── grid/            # 网格解析
│   ├── pieces/          # 拼图块解析
│   ├── req/             # 需求解析
│   ├── yolo/            # YOLO 工具
│   └── config/          # 配置文件
├── models/
│   ├── cell_detector.onnx    # 单元格检测模型
│   └── region_detector.onnx  # 区域检测模型
├── Dockerfile           # Docker 构建配置
├── pyproject.toml       # 项目配置和依赖
└── uv.lock              # 依赖锁定文件

📄 许可证

本项目采用 AGPL-3.0 许可证。

由于解析模块使用了基于 YOLO11 训练的模型，而 YOLO11 采用 AGPL-3.0 许可证，因此本项目也遵循 AGPL-3.0 许可证。