117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# Plan: Improve Bevel & Emboss MAE (138.99 → target < 20)
|
||
|
||
## Root Cause Analysis
|
||
|
||
The bevel/emboss MAE is **138.99** (vs drop shadow at 4.95). Three independent issues cause this:
|
||
|
||
### Issue 1: Compositing Base Color Mismatch (CRITICAL)
|
||
The tuning script (`tune_mae_bevel_emboss_kra_grid.rs:148-155`) hardcodes a **blue** shape `(73,73,255)`:
|
||
```rust
|
||
out[i * 4] = 73;
|
||
out[i * 4 + 1] = 73;
|
||
out[i * 4 + 2] = 255;
|
||
```
|
||
But the KRA ground truth PNGs have **black** (`black_rect_simple.kra`) or **red** (`red_rect_simple.kra`) shapes. Since Screen/Multiply blending is applied on top of this base color, the wrong base color produces completely wrong composite output.
|
||
|
||
### Issue 2: Linear Height Profile Produces Flat Plateaus (CRITICAL)
|
||
The current algorithm in `tuned.rs:67` uses a linear distance profile:
|
||
```rust
|
||
(d_in / radius).min(1.0) * radius
|
||
```
|
||
For a rectangle, the distance-to-edge gradient is a constant unit vector → the surface normal is constant → N·L produces a **flat plateau** across each edge. Krita produces a smooth gradient ramp because it uses a non-linear height profile (likely smoothstep or similar).
|
||
|
||
### Issue 3: Insufficient Parameter Grid (MODERATE)
|
||
Only 144 combos (4×6×6) tuning just `lighting_blur`, `hl_scale`, `sh_scale`. The algorithm's height profile shape — which is the primary factor — is not tunable at all.
|
||
|
||
---
|
||
|
||
## Implementation Steps
|
||
|
||
### Step 1: Fix Tuning Script Base Color (`hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs`)
|
||
|
||
**What:** Detect the actual shape color from the ground truth PNG instead of hardcoding blue.
|
||
|
||
**How:**
|
||
- Parse the filename to determine if it's from `black` or `red` base set (by checking the symlinked directory, or by sampling the PNG center pixels)
|
||
- Simpler approach: sample the center pixel of the ground truth image to detect the actual shape color
|
||
- Use the detected color as the base for compositing instead of `(73,73,255)`
|
||
|
||
**File:** `hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs`
|
||
|
||
### Step 2: Add Profile-Based Height Curve to `generate_bevel_tuned` (`hcie-fx/src/tuned.rs`)
|
||
|
||
**What:** Replace the linear height profile with a configurable power-curve profile and add it as a tunable parameter.
|
||
|
||
**How:**
|
||
- Add a new parameter `profile_exp: f32` (the exponent for the height profile)
|
||
- Height profile: `t = clamp(d_in / radius, 0, 1)` → `height = t.powf(profile_exp) * radius`
|
||
- `profile_exp = 1.0` → linear (current behavior)
|
||
- `profile_exp = 2.0` → quadratic (steeper falloff from edge)
|
||
- `profile_exp = 0.5` → sqrt (softer falloff)
|
||
- The smoothstep-like profile produces non-constant gradients on flat edges, eliminating the plateau
|
||
|
||
**File:** `hcie-fx/src/tuned.rs` (unlock `hcie-fx` first)
|
||
|
||
### Step 3: Expand the Grid Search Parameters
|
||
|
||
**What:** Add `profile_exp` to the grid and increase resolution.
|
||
|
||
**How:**
|
||
- `profile_exponents`: `[0.3, 0.5, 0.7, 1.0, 1.5, 2.0, 3.0]` (7 values)
|
||
- `lighting_blurs`: `[0, 1, 2, 3, 5]` (5 values)
|
||
- `hl_scales`: `[0.3, 0.5, 0.75, 1.0, 1.5, 2.0]` (6 values)
|
||
- `sh_scales`: `[0.3, 0.5, 0.75, 1.0, 1.5, 2.0]` (6 values)
|
||
- Total: 7 × 5 × 6 × 6 = **1,260 combos** × 32 samples = 40,320 evals (still fast)
|
||
|
||
**File:** `hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs`
|
||
|
||
### Step 4: Expand KRA Generator for More Sample Diversity
|
||
|
||
**What:** Add more parameter variations to the KRA generator to create a richer training set.
|
||
|
||
**How:**
|
||
- Add more `size` values: `[5.0, 10.0, 20.0, 30.0, 50.0]`
|
||
- Add more `depth` values: `[25.0, 50.0, 75.0, 100.0]`
|
||
- Add more `soften` values: `[0.0, 4.0, 8.0, 16.0]`
|
||
- Keep angles and directions as-is
|
||
- Total: 5 × 4 × 4 × 2 × 2 = 320 KRA files per base
|
||
|
||
**File:** `_tools/generate_bevel_emboss_kra_set.py`
|
||
|
||
### Step 5: Re-run Export + Tune
|
||
|
||
1. `python3 _tools/generate_bevel_emboss_kra_set.py` (generate new KRA set)
|
||
2. `python3 _tools/export_all_kra_to_png.py` (export to PNG via Krita)
|
||
3. `cargo run --release -p hcie-io --example tune_mae_bevel_emboss_kra_grid` (tune)
|
||
4. Verify MAE < 20
|
||
|
||
### Step 6: Update `emboss.rs` Production Code
|
||
|
||
**What:** Apply the best tuned parameters from the grid search to the production `generate_bevel_emboss` function in `emboss.rs`.
|
||
|
||
**How:**
|
||
- Read the results from `bevel_emboss_kra_grid_results.txt`
|
||
- Update the hardcoded values in `emboss.rs` between `BEGIN_TUNING_ZONE` / `END_TUNING_ZONE`
|
||
- This requires unlocking `hcie-fx` temporarily
|
||
|
||
**File:** `hcie-fx/src/emboss.rs` (unlock `hcie-fx` first)
|
||
|
||
---
|
||
|
||
## Files Modified
|
||
|
||
| File | Change |
|
||
|------|--------|
|
||
| `hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs` | Fix base color, add profile_exp, expand grid |
|
||
| `hcie-fx/src/tuned.rs` | Add profile_exp parameter, implement power-curve height profile |
|
||
| `hcie-fx/src/emboss.rs` | Apply final tuned parameters (BEGIN/END_TUNING_ZONE) |
|
||
| `_tools/generate_bevel_emboss_kra_set.py` | Expand parameter diversity |
|
||
|
||
## Verification
|
||
|
||
1. `cargo check -p hcie-fx` — compiles
|
||
2. `cargo check -p hcie-io --example tune_mae_bevel_emboss_kra_grid` — compiles
|
||
3. `python3 _tools/generate_bevel_emboss_kra_set.py` — generates expanded KRA set
|
||
4. `python3 _tools/export_all_kra_to_png.py` — exports PNGs
|
||
5. `cargo run --release -p hcie-io --example tune_mae_bevel_emboss_kra_grid` — runs tuning, MAE target < 20
|