# 基于矩形掩码修补的生成策略设计

## 背景

当前生成策略是从训练集采样地图，经 VQ-VAE 编码得到码本 z，再用**随机采样的 z**（而非真实 z）作为 MaskGIT 的条件进行三阶段级联生成。在当前数据规模下，模型难以从纯随机条件中学习到合理的生成分布，效果不佳。

## 新策略目标

降低任务难度：保持从训练集采样，但不再用随机 z，而是**在真实地图上施加随机矩形掩码**，让模型作为"修补（inpainting）"任务来完成。这样模型既有真实地图的结构先验（通过 z 条件），又有明确的局部填空目标。

## 核心改动

### 1. 掩码方式

**仅使用矩形分块掩码**（`dataset.py` `std_mask` 的第二种模式），不采用散点随机掩码：

- 在 13×13 网格上，反复放置随机矩形块（高宽 2~6），直到掩码格数达到目标比例
- 掩码比例可调，默认沿用 Beta(2,2) 采样（范围 [5%, 100%]），同时支持指定固定比例用于对照实验

### 2. 条件输入 z

不再随机采样 z，改为使用**被掩码地图经 VQ-VAE 编码后得到的真实 z**。这意味着：

- 编码器输入可能是部分掩码后的地图（掩码位置填 MASK_ID=7）
- VQ-VAE 从可见部分推断整体结构，得到的 z 携带地图的全局语义信息
- MaskGIT 以该 z 为条件，在掩码区域补全被遮盖的图块

### 3. 生成流程

仍然采用三阶段级联，但每个阶段统一使用同一份掩码布局：

```
输入: 完整地图 gt [13×13]
  ↓
生成矩形掩码 mask [13×13 bool]  (比率可调)
  ↓
inp = gt.copy(); inp[mask] = MASK_TOKEN
  ↓
VQ-VAE 编码 inp → z1, z2, z3
  ↓
Stage1: mg1(inp, z1) → 补全墙壁 (mask ∩ target=1)
Stage2: mg2(inp1+stage1_out, z2) → 补全门/怪物/入口
Stage3: mg3(inp2+stage2_out, z3) → 补全资源
  ↓
输出: 最终地图 + 逐阶段可视化对比
```

### 4. 与现有 `maskgit_sample` 的适配

现有 `maskgit_sample` 已支持 `keep_fixed` 参数，天然适配修补场景：

- `keep_fixed=True`（默认）：输入中已有的非掩码图块在生成过程中锁定不变，MaskGIT 仅填充掩码位
- 需要新增：将矩形掩码 `mask` 传入函数，使模型只尝试修改掩码区域

## 可调参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `mask_ratio` | 掩码比例，可指定固定值或 `None` 使用 Beta(2,2) 采样 | `None`（Beta 采样） |
| `block_h_range` | 矩形高度范围 | `(2, 7)` |
| `block_w_range` | 矩形宽度范围 | `(2, 7)` |
| `keep_fixed` | 三阶段是否锁定已有结构 | `(True, True, True)` |

## 实现要点

1. 将 `std_mask` 的矩形掩码生成逻辑提取为独立函数 `rect_mask(ratio, h_range, w_range) -> np.ndarray`
2. 新增 `inpaint_generate(map, mask, models, device)` 函数，包装完整修补流程
3. 验证时对同一张地图使用不同 `mask_ratio`（如 0%，30%，50%，70%）生成多组结果，横向对比
4. 可视化输出时同时展示：原始地图、掩码地图、各阶段生成结果、最终结果

## 预期效果

- 任务从"开放式生成"变为"约束式修补"，难度显著降低
- 模型可利用可见区域的上下文信息（如墙面走向、房间布局）推断掩码区域内容
- 不同掩码比例可衡量模型对空间结构的理解深度