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):

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:

(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