03-Parameters-and-Constraints

# LPGS Parameter System & Constraint Mechanisms

> **Doc Version**: v1.0.0 · **Algorithm Version**: LPGS v1.0

## 1. FittingSettings Parameter Reference

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `MaxShapes` | int | 500 | 50 ~ 5000 | Maximum number of shapes to generate during fitting |
| `Candidates` | int | 64 | 8 ~ 256 | Number of candidate shapes generated per iteration |
| `Speed` | int | 5 | 1 ~ 30 | Number of shapes added per frame (every 10ms) |
| `ReserveRatio` | double | 20 | 0 ~ 50 | Percentage of shape budget reserved for precision mode |
| `EnableCircle` | bool | true | — | Whether to enable circle primitives |
| `EnableEllipse` | bool | true | — | Whether to enable ellipse primitives |
| `EnableLine` | bool | true | — | Whether to enable line primitives |
| `PreserveTransparency` | bool | false | — | Whether to preserve the transparency channel |
| `BgColorIndex` | int | 0 | 0/1/2 | Background color: 0=black, 1=white, 2=transparent |
| `AlphaThreshold` | int | 128 | 0 ~ 255 | Transparency decision threshold |
| `EdgeAwareMode` | bool | false | — | Whether to enable edge-aware mode |
| `ScaleFactor` | double | 0 | 0 ~ 10 | Coordinate mapping scale factor (0=auto) |

---

## 2. Parameter Impact on Algorithm Behavior

### 2.1 MaxShapes — Shape Limit

`MaxShapes` directly controls the "resolution" of fitting:

- **Low values (50~100)**: Fast results, suitable for sketches/low-precision previews
- **Medium values (300~500)**: Balanced precision and speed, suitable for most scenarios
- **High values (1000~5000)**: High-precision fitting, should be used with precision mode

The actual number of available shapes is affected by `ReserveRatio`:

```
Standard fitting limit = MaxShapes × (1 - ReserveRatio / 100)
Precision fitting limit = MaxShapes
```

### 2.2 Candidates — Candidate Count

`Candidates` controls the breadth of search per iteration:

- **Low values (8~16)**: Narrow search range, fast but prone to local optima
- **Medium values (32~64)**: Recommended; balance between search breadth and speed
- **High values (128~256)**: Broad search range, higher probability of finding better shapes per step, but increased per-step cost

Parallel candidate evaluation can be enabled when `Candidates > 16` and CPU core count > 1.

### 2.3 Speed — Steps Per Frame

`Speed` controls the number of shapes computed between frames, affecting UI responsiveness:

- **Low values (1~3)**: Smooth UI, but longer total fitting time
- **Medium values (5~10)**: Recommended
- **High values (20~30)**: Fast fitting, but UI may lag

A 10ms `Task.Delay` between frames allows for UI refresh and cancellation checks.

### 2.4 ReserveRatio — Precision Reservation Ratio

`ReserveRatio` divides the shape budget into two phases:

```
Standard phase: uses MaxShapes × (1 - ReserveRatio/100) shapes
Precision phase: uses the remaining shape budget
```

- **0%**: No reservation; all shapes used in the standard phase
- **20% (default)**: Standard phase uses 80%, precision phase uses 20%
- **50%**: Equal split between standard and precision

---

## 3. Constraint Mechanisms

### 3.1 Edge-Aware Constraints

Edge-aware mode (`EdgeAwareMode`) uses two layers of constraints to prevent shapes from "overflowing" into transparent areas:

**Constraint 1: Size Limitation**

During shape generation and mutation, the maximum size is limited based on the distance from the shape center to the nearest transparent edge:

| Shape Type | Maximum Size Formula |
|------------|---------------------|
| 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)` |

Lines have a more lenient length limit (2.5× vs 0.8×) because extending along edge directions is reasonable.

**Constraint 2: Overflow Detection**

Even if a shape's size satisfies the limit, its interior pixels must still be checked for overflow:

```
For each pixel covered by the shape:
    Count total pixels as totalHits
    Count pixels in transparent areas as transparentHits

If transparentHits / totalHits > 5%:
    Reject the shape
```

The 5% tolerance allows slight edge overflow, avoiding excessive conservatism.

### 3.2 Opacity Constraints

A hard constraint is applied to opacity during color solving:

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

- **Lower bound 0.01**: Avoids fully transparent shapes (wasted computation)
- **Upper bound 0.99**: Avoids fully opaque shapes (preserves the ability to blend with the background, allowing subsequent shapes to correct)

### 3.3 Size Lower Bounds

All shape types have minimum size guarantees:

| Type | Minimum Size |
|------|-------------|
| circle | `Radius ≥ 2` |
| ellipse | `Rx ≥ 2, Ry ≥ 2` |
| line | `Rx ≥ 4, Ry ≥ 1` (during mutation: `Rx ≥ 5, Ry ≥ 1`) |

Overly small shapes contribute negligibly to error improvement but have the same computational cost, hence the lower bound filter.

### 3.4 Color Value Constraints

Color values are clamped to the `[0, 255]` range:

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

Least squares solving may produce color values outside the valid range (e.g., when a color "whiter than white" is needed to compensate); clamping ensures the output is always valid.

---

## 4. Primitive Geometry Determination

### 4.1 Point-in-Shape Test

**Circle**:

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

**Ellipse/Line**:

First transform the point into the ellipse's local coordinate system:

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

Then test:

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

A line is geometrically an extremely flat ellipse (`Rx >> Ry`) and uses the exact same test logic.

### 4.2 Bounding Box Calculation

**Circle**:

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

**Ellipse/Line**:

The axis-aligned bounding box (AABB) of a rotated ellipse is computed via the rotation matrix:

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

Bounding boxes limit the pixel traversal range, avoiding full-image scans.

---

## 5. Mutation Strategy

### 5.1 Mutation Parameters

| Type | Position Perturbation | Size Perturbation | Rotation Perturbation |
|------|----------------------|--------------------|-----------------------|
| 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 Mutation Formulas

**Position mutation**:

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

where `sizeParam` is `Radius` for circles, `Rx`/`Ry` for ellipses/lines. Position perturbation magnitude is proportional to shape size — large shapes can move farther, small shapes only make fine adjustments.

**Size mutation**:

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

Size changes are multiplicative (proportional scaling), ensuring positivity.

**Rotation mutation**:

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

Rotation is an additive perturbation; lines have a smaller range to maintain directional stability.

---

## 6. Fitting Mode Presets

LPGS provides two preset fitting modes:

### 6.1 Standard Fitting

- Background color: Black
- Preserve transparency: Off
- Edge-aware: Off
- Suitable for: Opaque images, solid background images

### 6.2 Transparent Background Fitting

- Background color: Transparent
- Preserve transparency: On
- Edge-aware: On
- Alpha threshold: 128
- Suitable for: PNG images with transparency

Transparent background mode automatically enables all transparency-related processing, including alpha pre-multiplication, edge distance map, and shape overflow detection.