Bug Resolution: Detail-Preserving Edge Sharpening, Adaptive Quantization & Dynamic Range Allocation (#18)

[everyday3d]

Bug Summary & Root Cause

Previous smoothing passes (bilateral filtering, morphological region merging, and flat layer quantization) introduced a blocky, washed-out look:

1. Detail Loss: High-pass micro-details (tree trunks, branches, fine silhouettes) were smoothed out by bilateral and spatial gradient smoothing passes.
2. Staircase Terracing & Blob Flattening: Flat discrete layer rounding forced every slope into blocky terraces, while morphological region merging wiped out thin 1–3 pixel features into dominant background neighbors.
3. Midtone Dynamic Range Compression: Setting default base layers to 5 and failing to re-normalize after filtering compressed midtones into a narrow 8-layer band, leaving more than half of the physical Z-depth completely unused.

Reproduction

1. Render a detailed landscape or portrait photo with fine tree branches or facial features.
2. Observe staircase terracing on slopes, blurred/merged tree branches, and flat washed-out midtone relief depth.

Resolution

• Detail-Preserving Edge-Aware Sharpening: Implemented applyEdgeAwareHeightmapSharpening using Sobel gradient magnitude with coring ramp (threshold 0.02, strength 0.85, max overshoot 0.15) to sharpen micro-details without boosting sensor noise on flat backgrounds.
• Adaptive Quantization Banding Control: Added adaptiveQuantizeHeightmapMatrix and updated applyMorphologicalRegionMerge with an edgeMask parameter to allow continuous micro-elevation in high-contrast/edge zones ($G \ge 0.08$) while preserving discrete snapping for flat backgrounds.
• Contrast-Stretched Dynamic Range Allocation: Re-normalized the heightmap dynamically so that shadow anchors utilize base layer 1 (0.16mm) and highlights reach the maximum physical Z-height limit, preventing midtone compression and utilizing 100% of the available relief Z-depth.
• Verification: Verified with 15 test suites and 87 unit tests.
• Reference: Resolved in Issue #18 and commit d253933.