AGENT INSTRUCTIONS

This crate (hcie-io) provides image I/O, KRA import/export, and SVG loading for the HCIE engine.

Permissions

Workspace-level hcie-blend, hcie-composite, hcie-protocol, and hcie-tile are used where applicable.

Zoom: Scroll wheel (exponential), Ctrl+scroll (10% step), buttons (-, +, 1:1, Reset)
Pan: Middle mouse drag
Layer Visibility: Eye button toggles, changes trigger re-composite
Checkerboard: Transparent canvas background, layer thumbnails show transparency
Compositing: Uses hcie-composite + hcie-blend for real blend-mode compositing
Layer Thumbnails: Nearest-neighbor resize, dirty flag updates only changed layers
PSD/KRA: Bottom layers at bottom of layer panel, composited image respects visibility
Save: Writes composited buffer to disk in chosen format

Read before change psd functions : Adobe Photoshop File Formats Specification.txt

effective_size() (shadow.rs:32): Clamps effect sizes to canvas max_dim, zeros effects with size > 2*max_dim. Fixes garbage size=131077 values from PSD parsing artifacts. Applied to all 8 effect types (bevel, satin, inner glow, inner shadow, stroke, drop shadow, outer glow, outside stroke).
Regional MAE analysis: Added to test_emboss_optimize — tile-based (32×32), per-channel, opaque-only, and horizontal/vertical line scanning for detailed pixel comparison.
.bak restore: Restored clean shadow.rs from backup, re-applied effective_size and max_size fixes.

NDL plateau: On simple shapes (rectangle), the height field gradient is constant across the bevel slope, so N·L produces a constant value → flat highlight/shadow plateau.
Photoshop's algorithm: Uses profile+direction approach — shadow=|dir_weight| × (1-profile) × depth, highlight=|dir_weight| × profile × depth, where profile = min(dist_to_edge / size, 1.0) and dir_weight = gradient·light. This produces linear transitions on simple shapes.
Hybrid challenge: Profile+direction works for emboss (opaque MAE 40.5→29.1 w/o NDL blur) but broke Sultan (4.27→7.40). Sultan needs NDL for its complex shapes. A hybrid approach (NDL × w + profile × (1-w)) blended before blur collapsed because the 25px lighting blur washes out the profile contribution.
Key experiment: With separate shadow/highlight buffers and NO extra blur, emboss edge matches perfectly (R=53 vs ref=53 at x=66), showing the profile+direction approach is correct. But Sultan needs the blur for smooth corners.

Emboss MAE: 120.9 (opaque 40.5). Plateau on Inner Bevel for simple shapes is unsolved.
Sultan: MAE=23.6 (NDL gradient-based bevel).
Bevel algorithm: Needs fundamental redesign — combine NDL (for complex shapes) with height-ratio (for linear edge transitions on simple shapes). The challenge is the 25px blur destroys profile-based corrections. Possible solutions: apply profile correction AFTER blur, or use adaptive blur based on gradient consistency.

hcie-fx/src/shadow.rs — effective_size() at line 32, all effect calls use it. generate_bevel_emboss() at line 652 (NDL-based).
hcie-io/src/test_psd_composite.rs — test_emboss_optimize() at line 1228.
/home/hc/Pictures/_psd_stil_test/emboss.psd — Test PSD (256×256, InnerBevel, depth=100, size=29).
/home/hc/Pictures/_psd_stil_test/emboss.png — Reference PNG.
/tmp/emboss_debug/ — Debug output.