feat(core): add software inpainting cleanup and UI/rendering fixes

Cleanup methods for residual artifacts after reverse alpha blending:
- NS (Navier-Stokes), TELEA (fast marching), Soft Inpaint (Gaussian blend)
- Gradient-weighted masks from watermark alpha for targeted cleanup
- Configurable strength (0-100%), radius (1-25px), method selection
- v5→v12b evolution: gradient weight + minimal boundary blur(σ=1.0)

UI improvements:
- Cleanup controls under Detected Info (teal header, Custom mode only)
- NS as default method, 85% strength, 10px radius, enabled by default
- Method combo → Strength slider → Radius slider control order

Rendering fixes:
- Fix window resize flickering: DXGI_SCALING_NONE (was STRETCH)
  DWM was stretching old back buffer during resize causing visual jitter
- Remove unnecessary std::floor layout workarounds

Author: allenk

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.21)
-project(GeminiWatermarkTool VERSION 0.2.2 LANGUAGES CXX)
+project(GeminiWatermarkTool VERSION 0.2.3 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)

README.md

@@ -40,11 +40,32 @@ The desktop GUI provides an interactive workflow for both single-image and batch
 
 - Drag & drop or open any supported image
 - Auto-detect watermark size (48×48 / 96×96) or select manually
-- **Custom watermark mode**: draw a region interactively, resize with 8-point anchors, fine-tune position with WASD keys
+- **Custom watermark mode**: draw a search region interactively, resize with 8-point anchors, fine-tune position with WASD keys
+- **Multi-scale guided detection (Snap Engine)**: coarse-to-fine NCC template matching auto-locks to the exact watermark position within your drawn region — supports variable sizes from 24–160px
 - Real-time before/after comparison (press **V**)
 - One-key processing (**X**) and revert (**Z**)
 - Zoom, pan (Space/Alt + drag, mouse wheel), and fit-to-window
 
+### Software Inpainting Cleanup (New in v0.2.3)
+
+![Software Inpainting](artworks/gui_inpaint_sw.gif)
+
+Reverse alpha blending is mathematically exact — but only when the image hasn't been resized, recompressed, or processed after watermarking. In practice, many images go through post-processing that breaks the pixel-perfect math, leaving faint residual artifacts after removal.
+
+**Software Inpainting** addresses this by applying a lightweight cleanup pass after the reverse blending step. It uses gradient-weighted masks derived from the watermark's own alpha channel to target only the residual pixels, leaving the rest of the image untouched.
+
+Three built-in methods are available:
+
+| Method | Description | Best for |
+|--------|-------------|----------|
+| **NS** (default) | Navier-Stokes based inpainting — propagates surrounding pixel flow into the damaged region | General-purpose cleanup with smooth results |
+| **TELEA** | Fast marching method — fills inward from boundary pixels based on distance weighting | Quick processing, good for small residuals |
+| **Soft Inpaint** | Gradient-weighted Gaussian blend — uses the watermark alpha as a soft mask for weighted blending | Preserving fine texture in photographic content |
+
+The cleanup controls appear automatically in **Custom** mode under the Detected Info panel. You can adjust the **method**, **strength** (0–100%), and **inpaint radius** (1–25 px) to fine-tune the result.
+
+> 🔮 **Coming soon**: A future release will introduce **lightweight AI-based inpainting** (DnCNN / FFDNet, ~2 MB models) for even better cleanup of residuals that conventional methods cannot fully resolve. Stay tuned.
+
 ### Batch Processing
 
 <!-- TODO: Replace with actual GIF -->
@@ -555,6 +576,17 @@ original = (watermarked - α × logo) / (1 - α)
 
 This mathematical inversion produces exact restoration of the original pixels.
 
+### Residual Cleanup (Software Inpainting)
+
+When images have been resized or recompressed after watermarking, the exact math no longer holds perfectly. A gradient-weighted inpainting pass can clean up the residual artifacts:
+
+```
+1. Compute gradient magnitude from watermark alpha channel
+2. Build soft weight mask: stronger where alpha gradient is high
+3. Apply selected inpainting method (NS / TELEA / Gaussian blend)
+4. Blend result using weight mask — only affected pixels are modified
+```
+
 ---
 
 ## Legal Disclaimer

artworks/gui_inpaint_sw.gif

@@ -17,6 +17,7 @@
 
 #include <opencv2/imgcodecs.hpp>
 #include <opencv2/imgproc.hpp>
+#include <opencv2/photo.hpp>
 #include <spdlog/spdlog.h>
 #include <fmt/format.h>
 #include <stdexcept>
@@ -713,6 +714,232 @@ GuidedDetectionResult WatermarkEngine::guided_detect(
     return result;
 }
 
+// =============================================================================
+// Inpaint Residual Cleanup
+// =============================================================================
+
+void WatermarkEngine::inpaint_residual(
+    cv::Mat& image,
+    const cv::Rect& region,
+    float strength,
+    InpaintMethod method,
+    int inpaint_radius,
+    int padding) const
+{
+    if (image.empty() || region.width < 4 || region.height < 4) {
+        return;
+    }
+
+    strength = std::clamp(strength, 0.0f, 1.0f);
+    if (strength < 0.001f) {
+        return;
+    }
+
+    // =========================================================================
+    // Common: Calculate padded region
+    // =========================================================================
+    cv::Rect padded_rect(
+        region.x - padding,
+        region.y - padding,
+        region.width + padding * 2,
+        region.height + padding * 2
+    );
+    padded_rect &= cv::Rect(0, 0, image.cols, image.rows);
+
+    if (padded_rect.width < 8 || padded_rect.height < 8) {
+        spdlog::warn("inpaint_residual: padded region too small");
+        return;
+    }
+
+    cv::Rect inner_rect(
+        region.x - padded_rect.x,
+        region.y - padded_rect.y,
+        region.width,
+        region.height
+    );
+    inner_rect &= cv::Rect(0, 0, padded_rect.width, padded_rect.height);
+
+    const char* method_name =
+        (method == InpaintMethod::GAUSSIAN) ? "Soft Inpaint" :
+        (method == InpaintMethod::TELEA)    ? "TELEA" : "NS";
+
+    // =========================================================================
+    // GAUSSIAN (Soft Inpaint): gradient weight + boundary feather
+    // =========================================================================
+    if (method == InpaintMethod::GAUSSIAN) {
+        // --- gradient weight (proven effective, unchanged) ---
+
+        // Compute alpha gradient to locate sparkle edges
+        const cv::Mat& source_alpha = alpha_map_large_;
+        cv::Mat alpha_resized;
+        int interp = (region.width > source_alpha.cols)
+            ? cv::INTER_LINEAR : cv::INTER_AREA;
+        cv::resize(source_alpha, alpha_resized,
+                   cv::Size(region.width, region.height), 0, 0, interp);
+
+        cv::Mat grad_x, grad_y, grad_mag;
+        cv::Sobel(alpha_resized, grad_x, CV_32F, 1, 0, 3);
+        cv::Sobel(alpha_resized, grad_y, CV_32F, 0, 1, 3);
+        cv::magnitude(grad_x, grad_y, grad_mag);
+
+        double grad_min, grad_max;
+        cv::minMaxLoc(grad_mag, &grad_min, &grad_max);
+        if (grad_max <= grad_min) {
+            spdlog::info("inpaint_residual: flat gradient, no edges found");
+            return;
+        }
+
+        // Normalize to 0.0-1.0
+        cv::Mat grad_norm = (grad_mag - grad_min) / (grad_max - grad_min);
+
+        // Gamma correction: sqrt expands weak gradient values
+        cv::Mat grad_weight;
+        cv::sqrt(grad_norm, grad_weight);
+
+        // Dilate to cover residual spread (v5 original: 5×5)
+        cv::Mat dk = cv::getStructuringElement(
+            cv::MORPH_ELLIPSE, cv::Size(5, 5));
+        cv::dilate(grad_weight, grad_weight, dk);
+
+        // Smooth weight for natural transitions (v5 original: σ=2.0)
+        cv::GaussianBlur(grad_weight, grad_weight, cv::Size(0, 0), 2.0);
+
+        // Scale by user strength
+        grad_weight *= strength;
+        cv::threshold(grad_weight, grad_weight, 1.0, 1.0, cv::THRESH_TRUNC);
+
+        // --- Smooth boundary transition (replaces v5 hard cutoff) ---
+        // Embed gradient weight into padded coordinate system
+        cv::Mat weight = cv::Mat::zeros(padded_rect.size(), CV_32F);
+        grad_weight.copyTo(weight(inner_rect));
+
+        // Tiny blur to soften the boundary transition
+        // σ=1.0 affects only ~3px at the inner_rect edge
+        // Interior (21px from edge on 42×42) is effectively unchanged
+        // Tips at boundary: weight transitions smoothly instead of hard cutoff
+        cv::GaussianBlur(weight, weight, cv::Size(0, 0), 1.0);
+
+        // --- Gaussian blur the image ---
+        int ksize = inpaint_radius * 2 + 1;
+        if (ksize % 2 == 0) ksize++;
+        ksize = std::max(ksize, 3);
+        double sigma = inpaint_radius * 0.8;
+
+        cv::Mat padded_area = image(padded_rect).clone();
+        cv::Mat blurred;
+        cv::GaussianBlur(padded_area, blurred, cv::Size(ksize, ksize), sigma);
+
+        // --- Per-pixel weighted blend ---
+        cv::Mat dst = image(padded_rect);
+        cv::Mat weight_3ch;
+        cv::merge(std::vector<cv::Mat>{weight, weight, weight}, weight_3ch);
+
+        cv::Mat dst_f, blurred_f, result_f;
+        dst.convertTo(dst_f, CV_32FC3);
+        blurred.convertTo(blurred_f, CV_32FC3);
+
+        cv::Mat one_minus_w = cv::Scalar(1.0, 1.0, 1.0) - weight_3ch;
+        cv::multiply(dst_f, one_minus_w, dst_f);
+        cv::multiply(blurred_f, weight_3ch, blurred_f);
+        result_f = dst_f + blurred_f;
+
+        result_f.convertTo(dst, CV_8UC3);
+
+        int active_pixels = cv::countNonZero(weight > 0.01f);
+        spdlog::info("inpaint_residual: {}, strength={:.0f}%, radius={}, sigma={:.1f}, "
+                     "{} active pixels",
+                     method_name, strength * 100.0f, inpaint_radius, sigma,
+                     active_pixels);
+        return;
+    }
+
+    // =========================================================================
+    // TELEA / NS: Sparse gradient mask + cv::inpaint
+    //
+    // Uses alpha map gradient to identify sparkle edges, creates binary mask,
+    // then runs OpenCV inpaint for structural reconstruction.
+    // These methods are best for edge artifacts on high-contrast boundaries
+    // (e.g. carpet ↔ floor edges that Gaussian blur would smear).
+    // =========================================================================
+
+    // Compute alpha gradient to locate sparkle edges
+    const cv::Mat& source_alpha = alpha_map_large_;
+    cv::Mat alpha_resized;
+    int interp = (region.width > source_alpha.cols) ? cv::INTER_LINEAR : cv::INTER_AREA;
+    cv::resize(source_alpha, alpha_resized,
+               cv::Size(region.width, region.height), 0, 0, interp);
+
+    cv::Mat grad_x, grad_y, grad_mag;
+    cv::Sobel(alpha_resized, grad_x, CV_32F, 1, 0, 3);
+    cv::Sobel(alpha_resized, grad_y, CV_32F, 0, 1, 3);
+    cv::magnitude(grad_x, grad_y, grad_mag);
+
+    // Normalize to 0-255
+    double grad_min, grad_max;
+    cv::minMaxLoc(grad_mag, &grad_min, &grad_max);
+    if (grad_max <= grad_min) {
+        spdlog::info("inpaint_residual: flat gradient, no edges found");
+        return;
+    }
+
+    cv::Mat grad_u8;
+    grad_mag.convertTo(grad_u8, CV_8U,
+                       255.0 / (grad_max - grad_min),
+                       -grad_min * 255.0 / (grad_max - grad_min));
+
+    // Create sparse binary mask at sparkle edges
+    cv::Mat sparse_mask;
+    cv::threshold(grad_u8, sparse_mask, 20, 255, cv::THRESH_BINARY);
+
+    // Dilate to cover residual spread (1-2px beyond gradient peak)
+    cv::Mat dilate_kernel = cv::getStructuringElement(
+        cv::MORPH_ELLIPSE, cv::Size(5, 5));
+    cv::dilate(sparse_mask, sparse_mask, dilate_kernel);
+
+    int masked_pixels = cv::countNonZero(sparse_mask);
+    if (masked_pixels == 0) {
+        spdlog::info("inpaint_residual: no edge pixels found, skipping");
+        return;
+    }
+
+    spdlog::info("inpaint_residual: {} sparse mask {}/{} pixels ({:.1f}%), "
+                 "strength={:.0f}%",
+                 method_name, masked_pixels, region.width * region.height,
+                 100.0f * masked_pixels / (region.width * region.height),
+                 strength * 100.0f);
+
+    // Embed mask into padded coordinate system
+    cv::Mat mask = cv::Mat::zeros(padded_rect.size(), CV_8UC1);
+    sparse_mask.copyTo(mask(inner_rect));
+
+    // Run cv::inpaint
+    cv::Mat padded_area = image(padded_rect).clone();
+    int cv_method = (method == InpaintMethod::TELEA)
+        ? cv::INPAINT_TELEA
+        : cv::INPAINT_NS;
+
+    cv::Mat inpainted;
+    cv::inpaint(padded_area, mask, inpainted, inpaint_radius, cv_method);
+
+    // Blend at masked pixels only (unmasked pixels stay untouched)
+    cv::Mat dst = image(padded_rect);
+    cv::Mat src_inner = dst(inner_rect);
+    cv::Mat inp_inner = inpainted(inner_rect);
+    cv::Mat mask_inner = mask(inner_rect);
+
+    if (strength >= 0.999f) {
+        inp_inner.copyTo(src_inner, mask_inner);
+    } else {
+        cv::Mat blended;
+        cv::addWeighted(src_inner, 1.0 - strength, inp_inner, strength, 0.0, blended);
+        blended.copyTo(src_inner, mask_inner);
+    }
+
+    spdlog::info("inpaint_residual: applied {} at {:.0f}% strength, radius={}, "
+                 "{} pixels repaired",
+                 method_name, strength * 100.0f, inpaint_radius, masked_pixels);
+}
+
 ProcessResult process_image(
     const std::filesystem::path& input_path,
     const std::filesystem::path& output_path,

src/core/watermark_engine.cpp

@@ -78,6 +78,15 @@ WatermarkPosition get_watermark_config(int image_width, int image_height);
  */
 WatermarkSize get_watermark_size(int image_width, int image_height);
 
+/**
+ * Inpaint method for residual cleanup after reverse alpha blend
+ */
+enum class InpaintMethod {
+    GAUSSIAN,   // Soft-blend: continuous gradient mask + Gaussian blur (recommended)
+    TELEA,      // OpenCV: Fast Marching Method (Telea, 2004)
+    NS          // OpenCV: Navier-Stokes (Bertalmio et al., 2001)
+};
+
 /**
  * Main watermark engine class
  *
@@ -212,6 +221,34 @@ class WatermarkEngine {
      */
     const cv::Mat& get_alpha_map(WatermarkSize size) const;
 
+    /**
+     * Apply inpaint cleanup on residual artifacts after reverse alpha blend.
+     *
+     * Uses SPARSE MASK derived from alpha map gradient — only repairs the
+     * sparkle edge pixels where interpolation broke the math, leaving
+     * correctly-restored pixels untouched.
+     *
+     * Two-stage pipeline:
+     *   1. Reverse alpha blend removes ~90% of watermark (mathematical precision)
+     *   2. This function cleans the remaining edge artifacts using cv::inpaint
+     *
+     * @param image       Image after reverse alpha blend (modified in-place)
+     * @param region      The watermark region (where reverse alpha was applied)
+     * @param strength    Blend strength: 0.0 = keep reverse-alpha result,
+     *                                    1.0 = fully replace with inpainted result
+     * @param method      Inpaint method (TELEA or NS)
+     * @param inpaint_radius  Inpaint radius for cv::inpaint (default: 3)
+     * @param padding     Context padding around region in pixels (default: 16)
+     */
+    void inpaint_residual(
+        cv::Mat& image,
+        const cv::Rect& region,
+        float strength = 0.85f,
+        InpaintMethod method = InpaintMethod::NS,
+        int inpaint_radius = 10,
+        int padding = 32
+    ) const;
+
 private:
     cv::Mat alpha_map_small_;   // 48x48 alpha map (CV_32FC1, 0.0-1.0)
     cv::Mat alpha_map_large_;   // 96x96 alpha map (CV_32FC1, 0.0-1.0)