03-参数体系与约束机制

# LPGS 参数体系与约束机制

> **文档版本**：v1.0.0 · **算法版本**：LPGS v1.0

## 1. FittingSettings 参数一览

| 参数 | 类型 | 默认值 | 范围 | 说明 |
|------|------|--------|------|------|
| `MaxShapes` | int | 500 | 50 ~ 5000 | 拟合过程最多生成的形状总数 |
| `Candidates` | int | 64 | 8 ~ 256 | 每轮迭代生成的候选形状数量 |
| `Speed` | int | 5 | 1 ~ 30 | 每帧（每 10ms）添加的形状数 |
| `ReserveRatio` | double | 20 | 0 ~ 50 | 为精度模式预留的形状配额百分比 |
| `EnableCircle` | bool | true | — | 是否启用圆形基元 |
| `EnableEllipse` | bool | true | — | 是否启用椭圆基元 |
| `EnableLine` | bool | true | — | 是否启用细线基元 |
| `PreserveTransparency` | bool | false | — | 是否保留透明通道 |
| `BgColorIndex` | int | 0 | 0/1/2 | 背景色：0=黑, 1=白, 2=透明 |
| `AlphaThreshold` | int | 128 | 0 ~ 255 | 透明度判定阈值 |
| `EdgeAwareMode` | bool | false | — | 是否启用边缘感知模式 |
| `ScaleFactor` | double | 0 | 0 ~ 10 | 坐标映射缩放因子（0=自动） |

---

## 2. 参数对算法行为的影响

### 2.1 MaxShapes — 形状上限

`MaxShapes` 直接控制拟合的"分辨率"：

- **低值（50~100）**：快速出结果，适合草图/低精度预览
- **中值（300~500）**：平衡精度与速度，适合大多数场景
- **高值（1000~5000）**：高精度拟合，需要配合精度模式使用

实际可用形状数受 `ReserveRatio` 影响：

```
标准拟合上限 = MaxShapes × (1 - ReserveRatio / 100)
精度拟合上限 = MaxShapes
```

### 2.2 Candidates — 候选数量

`Candidates` 控制每轮搜索的广度：

- **低值（8~16）**：搜索范围窄，速度快但容易陷入局部最优
- **中值（32~64）**：推荐值，搜索广度与速度的平衡
- **高值（128~256）**：搜索范围广，每步找到更好形状的概率更高，但单步耗时增加

当 `Candidates > 16` 且 CPU 核心数 > 1 时，可启用并行评估候选形状。

### 2.3 Speed — 每帧步数

`Speed` 控制帧间计算的形状数，影响 UI 响应性：

- **低值（1~3）**：UI 流畅，但总拟合时间长
- **中值（5~10）**：推荐值
- **高值（20~30）**：拟合速度快，但 UI 可能卡顿

每帧之间有 10ms 的 `Task.Delay`，用于 UI 刷新和取消检测。

### 2.4 ReserveRatio — 精度预留比例

`ReserveRatio` 将形状配额分为两个阶段：

```
标准阶段：使用 MaxShapes × (1 - ReserveRatio/100) 个形状
精度阶段：使用剩余的形状配额
```

- **0%**：不预留，所有形状在标准阶段使用
- **20%（默认）**：标准阶段用 80%，精度阶段用 20%
- **50%**：标准与精度各占一半

---

## 3. 约束机制

### 3.1 边缘感知约束

边缘感知模式（`EdgeAwareMode`）通过两层约束防止形状"溢出"到透明区域：

**约束一：尺寸限制**

在形状生成和变异时，根据形状中心到最近透明边缘的距离，限制形状的最大尺寸：

| 形状类型 | 最大尺寸公式 |
|---------|------------|
| circle | `maxRadius = max(3, edgeDist × 0.8)` |
| ellipse | `maxRx = max(3, edgeDist × 0.8)`, `maxRy = max(3, edgeDist × 0.8)` |
| line | `maxLen = max(3, edgeDist × 2.5)` |

细线（line）的长度限制更宽松（2.5 倍 vs 0.8 倍），因为细线沿边缘方向延伸是合理的。

**约束二：越界检测**

即使形状尺寸满足限制，仍需检查形状内部像素是否越界：

```
对于形状覆盖的每个像素:
    统计总像素数 totalHits
    统计落在透明区域的像素数 transparentHits

若 transparentHits / totalHits > 5%:
    拒绝该形状
```

5% 的容忍度允许形状有轻微的边缘溢出，避免过度保守。

### 3.2 透明度约束

颜色求解过程中对透明度施加硬约束：

```
alpha = Clamp(alpha, 0.01, 0.99)
```

- **下界 0.01**：避免完全透明的形状（无意义的计算浪费）
- **上界 0.99**：避免完全不透明的形状（保留与背景混合的能力，使后续形状可以覆盖修正）

### 3.3 尺寸下界

所有形状类型都有最小尺寸保证：

| 类型 | 最小尺寸 |
|------|---------|
| circle | `Radius ≥ 2` |
| ellipse | `Rx ≥ 2, Ry ≥ 2` |
| line | `Rx ≥ 4, Ry ≥ 1`（变异时 `Rx ≥ 5, Ry ≥ 1`） |

过小的形状对误差改进的贡献微乎其微，但计算开销不变，因此需要下界过滤。

### 3.4 颜色值约束

颜色值被钳位到 `[0, 255]` 范围：

```
sR = Clamp(round(...), 0, 255)
sG = Clamp(round(...), 0, 255)
sB = Clamp(round(...), 0, 255)
```

最小二乘求解可能产生超出合法范围的颜色值（例如当需要"比白色更白"的颜色来补偿时），钳位确保输出始终合法。

---

## 4. 基元几何判定

### 4.1 点在形状内的判定

**圆形**：

```
inside(px, py) ⟺ (px - cx)² + (py - cy)² ≤ r²
```

**椭圆/细线**：

先将点变换到椭圆的局部坐标系：

```
lx =  (px - cx) × cos(θ) + (py - cy) × sin(θ)
ly = -(px - cx) × sin(θ) + (py - cy) × cos(θ)
```

然后判定：

```
inside ⟺ (lx² / rx²) + (ly² / ry²) ≤ 1  且  rx ≥ 1, ry ≥ 1
```

细线在几何上就是一个极扁的椭圆（`Rx >> Ry`），使用完全相同的判定逻辑。

### 4.2 包围盒计算

**圆形**：

```
x0 = X - Radius,  y0 = Y - Radius
x1 = X + Radius,  y1 = Y + Radius
```

**椭圆/细线**：

旋转椭圆的轴对齐包围盒（AABB）通过旋转矩阵计算：

```
x0 = X - w_bound,  y0 = Y - h_bound
x1 = X + w_bound,  y1 = Y + h_bound
```

包围盒用于限制像素遍历范围，避免全图扫描。

---

## 5. 变异策略

### 5.1 变异参数

| 参数 | 位置扰动强度 | 尺寸扰动强度 | 旋转扰动 |
|------|------------|------------|---------|
| circle | `posStr = 0.3` | `sizeStr = 0.3` | — |
| ellipse | `posStr = 0.3` | `sizeStr = 0.3` | `±0.4 rad` |
| line | `posStr = 0.3` | `sizeStr = 0.3` | `±0.3 rad` |

### 5.2 变异公式

**位置变异**：

```
X' = clamp(X + (r - 0.5) × 2 × sizeParam × posStr, 0, imgW)
```

其中 `sizeParam` 对 circle 为 `Radius`，对 ellipse/line 为 `Rx`/`Ry`。位置扰动幅度与形状尺寸成正比——大形状可以移动更远，小形状只做微调。

**尺寸变异**：

```
size' = max(minSize, size × (1 + (r - 0.5) × 2 × sizeStr))
```

尺寸变化是乘性的（比例缩放），保证正定性。

**旋转变异**：

```
θ' = θ + (r - 0.5) × rotRange
```

旋转是加性扰动，细线的旋转范围更小以保持方向稳定性。

---

## 6. 拟合方式预设

LPGS 提供两种预设的拟合方式：

### 6.1 标准拟合

- 背景色：黑色
- 保留透明：关闭
- 边缘感知：关闭
- 适用于：不透明图像、纯色背景图像

### 6.2 透明底拟合

- 背景色：透明
- 保留透明：开启
- 边缘感知：开启
- Alpha 阈值：128
- 适用于：带透明通道的 PNG 图像

透明底模式自动启用所有透明度相关的处理逻辑，包括 Alpha 预混合、边缘距离图、形状越界检测等。