hcie-rust-v3.05/.kilo/plans/bevel-emboss-improve-plan.md

# 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