---
name: "floorplan-recognizer"
description: >
  户型图识别工具。当需要"识别户型图"、"解析户型"、"提取户型信息"、"看户型有哪些房间/窗户"、
  "floor plan recognition"、"户型图推导输入"时使用。用 qwen-vl-max 把链家等房产户型图解析成
  结构化 JSON（房间/朝向/窗户形态），并生成「路径 B 文字钉死」片段，作为居民楼立面推导的可靠输入。
---

# 户型图识别工具 (Floorplan Recognizer)

> 户型图图片 → qwen-vl-max 解析 → 结构化 JSON + 「路径 B 文字钉死」片段

## 为什么需要它

AI 生图模型（GPT-Image-2）独立读户型图不可靠——会用"住宅常识"脑补（默认卧室大窗、阳台落地窗、漏房间），
导致路径 B「户型图推导」每张图都要**人工逐项校验窗户形态与比例**（见 `docs/art/美术风格指南.md` 路径 B 劣势）。

本工具先用专门的视觉大模型 qwen-vl-max 把户型图**解析成结构化清单**，把"人工逐项校验"降级为
"AI 出清单 + 人工快速核对"。

> 评测结论（详见 `ai-art-research/生成结果/户型图识别评测/评测对比.md`）：qwen-vl-max 在房间完整性、
> 面积 OCR 精度、备注诚实度上领先 gpt-4o / qwen-vl-plus / gpt-4o-mini。

## 触发条件

- 用户说"识别/解析这张户型图"、"提取户型信息"、"看看这个户型有哪些房间/窗户"
- 路径 B 户型图推导前，需要可靠的「房间 + 窗户形态」清单作为"文字钉死"依据
- 用户提供了一张链家/房产户型图要求分析

## 工具位置

```
ai-art-research/tools/
  floorplan_parse.py    # 生产版（固定 qwen-vl-max，生成文字钉死片段）⭐ 本技能用这个
  floorplan_eval.py     # 评测版（可换模型对比）
```

依赖 `ai-art-research/.env` 的 `APIYI_API_KEY`（与 `image_gen.py` 共用）。

## 工作流

### 步骤 1：解析户型图

```bash
cd ai-art-research
python tools/floorplan_parse.py --image <户型图路径>
```

产出（存 `生成结果/户型图识别/`）：
- `<时间戳>_apiyi_qwen-vl-max.json` — 结构化结果（房间/朝向/窗户/立面对应表）
- `<时间戳>_apiyi_qwen-vl-max.钉死.md` — 「路径 B 文字钉死」片段（可直接粘进生图 prompt）
- `.meta.json` — 调用元数据

### 步骤 2：人工快速核对

对照原图，重点核对「文字钉死」片段里的 ⚠️ 核对项（这些是评测发现的脑补重灾区）：
- **卫生间朝向 / 是否暗卫**（模型间分歧最大）
- **阳台朝向**（皆南 vs 一南一北类分歧）
- **窗户类型 / 大小**（均为推测值）

房间数量与单间面积经评测高度可信（qwen-vl-max 与 gpt-4o 面积 OCR 完全一致），一般无需核对。

### 步骤 3：喂给路径 B 生图

把核对后的「文字钉死」片段贴进 `ai-art-research/prompts/居民楼-*-户型图推导-v*.txt` 的窗户形态段落，
作为户型图推导立面的"文字钉死"依据，再走 `image_gen.py --fuse` 生图。

## 注意事项

- 走 API易 的 **vision chat 接口（按 token 计费）**，与生图通道（codex 按订阅 / apiyi 按张）独立，互不影响
- 窗户类型/朝向/大小是模型**推测**，务必核对；房间结构与面积可信
- 若某张图效果不稳，可用 `floorplan_eval.py --image <图> -m <模型>` 换模型对比（参考评测对比.md）
- 链家等彩色标准化户型图适配良好；纯手绘/模糊扫描图效果会下降
- `ai-art-research/` 被项目 `.ignore` 屏蔽，操作需用显式路径（不进 Glob 检索）