leptonica 0.4.0

//! Adaptive mapping operations
//!
//! Implements local adaptive image enhancement techniques including:
//!
//! - Background normalization: Compensates for uneven illumination
//! - Contrast normalization: Expands local dynamic range
//!
//! These operations are tile-based and work well for:
//! - Document image enhancement
//! - Preprocessing for OCR
//! - Correcting uneven lighting conditions
//!
//! # Example
//!
//! ```ignore
//! use leptonica::filter::adaptmap::{background_norm_simple, contrast_norm_simple};
//!
//! // Normalize background with default parameters
//! let normalized = background_norm_simple(&pix)?;
//!
//! // Apply local contrast normalization
//! let enhanced = contrast_norm_simple(&pix)?;
//! ```

use crate::core::{Pix, PixelDepth, pixel};
use crate::filter::{FilterError, FilterResult};

// ============================================================================
// Default parameters (matching C version defaults)
// ============================================================================

/// Default tile width for background normalization
pub const DEFAULT_TILE_WIDTH: u32 = 10;

/// Default tile height for background normalization
pub const DEFAULT_TILE_HEIGHT: u32 = 15;

/// Default foreground threshold (pixels below this are considered foreground)
pub const DEFAULT_FG_THRESHOLD: u32 = 60;

/// Default minimum count of background pixels required per tile
pub const DEFAULT_MIN_COUNT: u32 = 40;

/// Default target background value after normalization
pub const DEFAULT_BG_VAL: u32 = 200;

/// Default smoothing half-width in X direction
pub const DEFAULT_SMOOTH_X: u32 = 2;

/// Default smoothing half-width in Y direction
pub const DEFAULT_SMOOTH_Y: u32 = 1;

// Default parameters for contrast normalization
/// Default minimum difference for contrast normalization
pub const DEFAULT_MIN_DIFF: u32 = 50;

/// Default tile size for contrast normalization
pub const DEFAULT_CONTRAST_TILE_SIZE: u32 = 20;

// ============================================================================
// Option structures
// ============================================================================

/// Options for background normalization
#[derive(Debug, Clone)]
pub struct BackgroundNormOptions {
    /// Tile width in pixels (minimum 4)
    pub tile_width: u32,
    /// Tile height in pixels (minimum 4)
    pub tile_height: u32,
    /// Foreground threshold (pixels below this are excluded from background)
    pub fg_threshold: u32,
    /// Minimum count of background pixels required per tile
    pub min_count: u32,
    /// Target background value after normalization (typically 128-240)
    pub bg_val: u32,
    /// Half-width of smoothing kernel in X direction (0 = no smoothing)
    pub smooth_x: u32,
    /// Half-width of smoothing kernel in Y direction (0 = no smoothing)
    pub smooth_y: u32,
}

impl Default for BackgroundNormOptions {
    fn default() -> Self {
        Self {
            tile_width: DEFAULT_TILE_WIDTH,
            tile_height: DEFAULT_TILE_HEIGHT,
            fg_threshold: DEFAULT_FG_THRESHOLD,
            min_count: DEFAULT_MIN_COUNT,
            bg_val: DEFAULT_BG_VAL,
            smooth_x: DEFAULT_SMOOTH_X,
            smooth_y: DEFAULT_SMOOTH_Y,
        }
    }
}

/// Options for contrast normalization
#[derive(Debug, Clone)]
pub struct ContrastNormOptions {
    /// Tile width in pixels (minimum 5)
    pub tile_width: u32,
    /// Tile height in pixels (minimum 5)
    pub tile_height: u32,
    /// Minimum difference (max - min) to accept as valid contrast
    pub min_diff: u32,
    /// Half-width of smoothing kernel in X direction (0-8)
    pub smooth_x: u32,
    /// Half-width of smoothing kernel in Y direction (0-8)
    pub smooth_y: u32,
}

impl Default for ContrastNormOptions {
    fn default() -> Self {
        Self {
            tile_width: DEFAULT_CONTRAST_TILE_SIZE,
            tile_height: DEFAULT_CONTRAST_TILE_SIZE,
            min_diff: DEFAULT_MIN_DIFF,
            smooth_x: 2,
            smooth_y: 2,
        }
    }
}

// ============================================================================
// Public API: Background normalization
// ============================================================================

/// Normalize image background with default parameters
///
/// This is a simplified interface that uses default tile sizes and parameters.
/// Suitable for most document images.
///
/// # Arguments
/// * `pix` - Input 8bpp grayscale or 32bpp RGB image
///
/// # Returns
/// Background-normalized image with the same depth as input
///
/// # Example
/// ```ignore
/// let normalized = background_norm_simple(&document_image)?;
/// ```
pub fn background_norm_simple(pix: &Pix) -> FilterResult<Pix> {
    background_norm(pix, &BackgroundNormOptions::default())
}

/// Normalize image background with custom parameters
///
/// Performs adaptive background normalization by:
/// 1. Estimating background values in each tile
/// 2. Creating an inverted background map
/// 3. Applying the map to normalize the image
///
/// # Arguments
/// * `pix` - Input 8bpp grayscale or 32bpp RGB image
/// * `options` - Normalization parameters
///
/// # Returns
/// Background-normalized image
pub fn background_norm(pix: &Pix, options: &BackgroundNormOptions) -> FilterResult<Pix> {
    // 8 bpp colormapped pixels carry palette indices; tile statistics on
    // those indices produce nonsense (and the strict C-aligned
    // fill_map_holes will error on the resulting all-zero map). Decode
    // the colormap up front so callers don't have to. C leptonica returns
    // an explicit error here; we choose to be a touch more ergonomic.
    if pix.colormap().is_some() {
        let decoded = pix.remove_colormap(crate::core::pix::RemoveColormapTarget::ToGrayscale)?;
        return background_norm(&decoded, options);
    }

    // Validate parameters
    if options.tile_width < 4 || options.tile_height < 4 {
        return Err(FilterError::InvalidParameters(
            "tile dimensions must be >= 4".to_string(),
        ));
    }
    if options.bg_val < 128 || options.bg_val > 255 {
        return Err(FilterError::InvalidParameters(
            "bg_val should be between 128 and 255".to_string(),
        ));
    }

    // Adjust min_count if too large for tile
    let mut min_count = options.min_count;
    if min_count > options.tile_width * options.tile_height {
        min_count = (options.tile_width * options.tile_height) / 3;
    }

    match pix.depth() {
        PixelDepth::Bit8 => background_norm_gray(pix, options, min_count),
        PixelDepth::Bit32 => background_norm_color(pix, options, min_count),
        _ => Err(FilterError::UnsupportedDepth {
            expected: "8 or 32 bpp",
            actual: pix.depth().bits(),
        }),
    }
}

// ============================================================================
// Internal: Grayscale background normalization
// ============================================================================

fn background_norm_gray(
    pix: &Pix,
    options: &BackgroundNormOptions,
    min_count: u32,
) -> FilterResult<Pix> {
    // Get background map
    let bg_map = get_background_gray_map_inner(
        pix,
        options.tile_width,
        options.tile_height,
        options.fg_threshold,
        min_count,
    )?;
    // Get inverted background map
    let inv_map =
        get_inv_background_map_inner(&bg_map, options.bg_val, options.smooth_x, options.smooth_y)?;

    // Apply the map
    apply_inv_background_gray_map_inner(pix, &inv_map, options.tile_width, options.tile_height)
}

fn background_norm_color(
    pix: &Pix,
    options: &BackgroundNormOptions,
    min_count: u32,
) -> FilterResult<Pix> {
    // Build the three bg maps in a single tile pass against a SHARED
    // foreground mask (matches C `pixGetBackgroundRGBMap`).
    let (bg_map_r, bg_map_g, bg_map_b) = get_background_rgb_map_inner(
        pix,
        options.tile_width,
        options.tile_height,
        options.fg_threshold,
        min_count,
    )?;

    // Get inverted maps
    let inv_map_r = get_inv_background_map_inner(
        &bg_map_r,
        options.bg_val,
        options.smooth_x,
        options.smooth_y,
    )?;
    let inv_map_g = get_inv_background_map_inner(
        &bg_map_g,
        options.bg_val,
        options.smooth_x,
        options.smooth_y,
    )?;
    let inv_map_b = get_inv_background_map_inner(
        &bg_map_b,
        options.bg_val,
        options.smooth_x,
        options.smooth_y,
    )?;

    // Apply maps and combine channels.
    let (pixr, pixg, pixb) = extract_rgb_channels(pix)?;
    let result_r = apply_inv_background_gray_map_inner(
        &pixr,
        &inv_map_r,
        options.tile_width,
        options.tile_height,
    )?;
    let result_g = apply_inv_background_gray_map_inner(
        &pixg,
        &inv_map_g,
        options.tile_width,
        options.tile_height,
    )?;
    let result_b = apply_inv_background_gray_map_inner(
        &pixb,
        &inv_map_b,
        options.tile_width,
        options.tile_height,
    )?;

    // Combine channels back into RGB
    combine_rgb_channels(&result_r, &result_g, &result_b, pix.spp())
}

// ============================================================================
// Public API: Background map generation
// ============================================================================

/// Generate background map for a grayscale image.
///
/// C版: `pixGetBackgroundGrayMap()` in `adaptmap.c`
///
/// Estimates the background value for each tile in the image.
/// Foreground pixels (below `fg_threshold`) are excluded.
/// Tiles with fewer than `min_count` background pixels are left as holes
/// and filled by propagation.
///
/// # Arguments
/// * `pix` - Input 8bpp grayscale image
/// * `mask` - Optional mask (currently unused, reserved for future)
/// * `tile_w` - Tile width in pixels
/// * `tile_h` - Tile height in pixels
/// * `fg_threshold` - Pixels below this value are considered foreground
/// * `min_count` - Minimum background pixels required per tile
pub fn get_background_gray_map(
    pix: &Pix,
    mask: Option<&Pix>,
    tile_w: u32,
    tile_h: u32,
    fg_threshold: u32,
    min_count: u32,
) -> FilterResult<Pix> {
    // Decode any colormap up front (palette indices are not gray values).
    if pix.colormap().is_some() {
        let decoded = pix.remove_colormap(crate::core::pix::RemoveColormapTarget::ToGrayscale)?;
        return get_background_gray_map(&decoded, mask, tile_w, tile_h, fg_threshold, min_count);
    }
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    if fg_threshold > 255 {
        return Err(FilterError::InvalidParameters(format!(
            "fg_threshold must be in 0..=255 (got {fg_threshold})"
        )));
    }
    // Image-mask (`pixim`) handling is reserved for a future plan-029 PR;
    // the parameter is accepted for forward compatibility but ignored.
    let _ = mask;
    get_background_gray_map_inner(pix, tile_w, tile_h, fg_threshold, min_count)
}

/// Generate background maps for each RGB channel.
///
/// C版: `pixGetBackgroundRGBMap()` in `adaptmap.c`
///
/// Builds three 8 bpp tile-resolution maps for the R, G, B channels of a
/// 32 bpp RGB input. A **single foreground mask is shared** across all
/// three channels (constructed from a fast grayscale conversion of `pix`
/// via `Pix::convert_rgb_to_gray_fast`, then `threshold_to_binary` +
/// `morph_sequence("d7.1 + d1.7")`), and per-tile R/G/B sums are
/// accumulated in a **single pass** against that mask. Each tile's
/// average is written to its position in the corresponding map iff the
/// number of non-foreground samples reaches `min_count`. Holes are then
/// filled with `fill_map_holes_inner` per channel.
///
/// # Arguments
/// * `pix` - Input 32bpp RGB image
/// * `mask` - Optional image mask; **currently ignored**, accepted for
///   forward compatibility (image-mask handling is a plan-029 follow-up)
/// * `pixg` - Optional caller-supplied grayscale version; **currently
///   ignored**. The shared fg mask is always built from
///   `pixConvertRGBToGrayFast` internally
/// * `tile_w` - Tile width
/// * `tile_h` - Tile height
/// * `fg_threshold` - Foreground threshold (`<` is foreground)
/// * `min_count` - Minimum non-foreground samples required for a tile
///   to receive a non-zero map entry
///
/// # Returns
/// Tuple of (red_map, green_map, blue_map) as 8bpp images
pub fn get_background_rgb_map(
    pix: &Pix,
    mask: Option<&Pix>,
    pixg: Option<&Pix>,
    tile_w: u32,
    tile_h: u32,
    fg_threshold: u32,
    min_count: u32,
) -> FilterResult<(Pix, Pix, Pix)> {
    // `mask` (image mask) and `pixg` (caller-supplied grayscale version)
    // are accepted for forward compatibility; image-mask + caller-gray
    // handling is reserved for a follow-up plan-029 PR. Today the
    // shared fg mask is always built from `pixConvertRGBToGrayFast`.
    let _ = mask;
    let _ = pixg;
    get_background_rgb_map_inner(pix, tile_w, tile_h, fg_threshold, min_count)
}

/// Fill holes (zero values) in a background or foreground map.
///
/// C版: `pixFillMapHoles()` in `adaptmap.c`
///
/// Get a grayscale foreground map from an 8bpp image.
///
/// C equivalent: `pixGetForegroundGrayMap` in `adaptmap.c`
///
/// Each (sx, sy) tile of the source gets mapped to one pixel in the output,
/// estimating the darkest (foreground) value within each tile. Pixels in
/// 'image' regions (specified by `mask`) are set to 0.
///
/// The procedure is:
/// 1. Reduce 2x by sampling
/// 2. Paint 'image' mask pixels white
/// 3. Min reduction downscaling by (sx, sy)
/// 4. Threshold to identify fg; paint bg to 255
/// 5. Expand replicate 2x
/// 6. Fill holes by propagation
/// 7. Smooth with blockconv (half-width 8)
/// 8. Paint 'image' regions black
pub fn get_foreground_gray_map(
    pix: &Pix,
    mask: Option<&Pix>,
    sx: u32,
    sy: u32,
    thresh: u32,
) -> FilterResult<Pix> {
    use crate::color::threshold::threshold_to_binary;
    use crate::filter::block_conv::blockconv;
    use crate::filter::rank::{MinMaxOp, scale_gray_min_max};
    use crate::transform::binreduce::reduce_rank_binary_2;
    use crate::transform::scale::{expand_replicate, scale_by_sampling};

    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8-bpp grayscale",
            actual: pix.depth().bits(),
        });
    }
    if let Some(m) = mask
        && m.depth() != PixelDepth::Bit1
    {
        return Err(FilterError::InvalidParameters(
            "mask must be 1 bpp".to_string(),
        ));
    }
    if sx < 2 || sy < 2 {
        return Err(FilterError::InvalidParameters(
            "sx and sy must be >= 2".to_string(),
        ));
    }

    let w = pix.width();
    let h = pix.height();
    let wd = w.div_ceil(sx);
    let hd = h.div_ceil(sy);

    // Check if mask covers everything (all image pixels → return zeros)
    let fg_pixels;
    if let Some(m) = mask {
        let inverted = m.invert();
        if inverted.is_zero() {
            // Entire image is masked → return all-zero output
            return Ok(Pix::new(wd, hd, PixelDepth::Bit8)?);
        }
        fg_pixels = !m.is_zero();
    } else {
        fg_pixels = false;
    }

    // 2x subsampling
    let mut pixs2 = scale_by_sampling(pix, 0.5, 0.5)?;

    // Paint white through 'image' mask
    if let Some(m) = mask
        && fg_pixels
    {
        let pixim2 = reduce_rank_binary_2(m, 1)?;
        let mut pixs2_mut = pixs2.try_into_mut().unwrap();
        pixs2_mut.paint_through_mask(&pixim2, 0, 0, 255)?;
        pixs2 = pixs2_mut.into();
    }

    // Min downscaling; total reduction (2 * sx, 2 * sy) → output is roughly (w/(2*sx), h/(2*sy))
    let pixt1 = scale_gray_min_max(&pixs2, sx, sy, MinMaxOp::Min)?;

    // Validate thresh fits in u8
    if thresh > u8::MAX as u32 {
        return Err(FilterError::InvalidParameters(format!(
            "thresh value {} exceeds maximum of 255",
            thresh
        )));
    }

    // Threshold to identify fg; paint bg pixels white
    let pixb = threshold_to_binary(&pixt1, thresh as u8)
        .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;
    let pixb_inv = pixb.invert();
    let pixt1_mut_pix: Pix = {
        let mut pixt1_mut = pixt1.try_into_mut().unwrap();
        pixt1_mut.paint_through_mask(&pixb_inv, 0, 0, 255)?;
        pixt1_mut.into()
    };

    // Replicative expansion by 2x
    let pixt2 = expand_replicate(&pixt1_mut_pix, 2)?;

    // Fill holes in fg by propagation
    let valid_x = (w / sx).min(pixt2.width());
    let valid_y = (h / sy).min(pixt2.height());
    let pixt2_filled = fill_map_holes(&pixt2, valid_x, valid_y)?;

    // Smooth with 17x17 kernel (blockconv half-width 8)
    let pixt3 = blockconv(&pixt2_filled, 8, 8)?;

    // Copy to output dimensions
    let pixd = Pix::new(wd, hd, PixelDepth::Bit8)?;
    let mut pixd_mut = pixd.try_into_mut().unwrap();
    let copy_w = wd.min(pixt3.width());
    let copy_h = hd.min(pixt3.height());
    for y in 0..copy_h {
        for x in 0..copy_w {
            let val = pixt3.get_pixel(x, y).unwrap_or(0);
            pixd_mut.set_pixel_unchecked(x, y, val);
        }
    }

    // Paint 'image' regions black
    if let Some(m) = mask {
        let pixims = scale_by_sampling(m, 1.0 / sx as f32, 1.0 / sy as f32)?;
        pixd_mut.paint_through_mask(&pixims, 0, 0, 0)?;
    }

    Ok(pixd_mut.into())
}

/// Fill 0-valued holes in an 8 bpp tile-resolution map by C-aligned
/// column-major replication.
///
/// `nx` and `ny` are the number of fully-covered tile columns / rows; the
/// rightmost column and bottommost row of `pix` may correspond to partial
/// tiles when `pix.width() > nx` or `pix.height() > ny`.
///
/// Mirrors C `pixFillMapHoles(pix, nx, ny, L_FILL_BLACK)` in
/// `reference/leptonica/src/adaptmap.c`. The algorithm has three phases:
/// 1. For each column `j in 0..nx`, find the first non-zero pixel in
///    rows `0..ny`. Replicate that value upward, then sweep downward
///    through `0..h` propagating the most recent valid value into holes.
/// 2. For columns with no valid pixel, replicate from the nearest valid
///    column — backward to column 0, forward through `nx-1`.
/// 3. If `w > nx`, replicate column `w-2` into column `w-1` to fill the
///    last partial-tile column.
///
/// Returns `Err(FilterError::InvalidParameters)` if no column carries any
/// non-zero data (matches the C `nmiss == nx` warning path).
pub fn fill_map_holes(pix: &Pix, nx: u32, ny: u32) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    let w = pix.width();
    let h = pix.height();
    // C contract (adaptmap.c): nx == w || nx == w - 1 (ditto for ny vs h).
    // Phase 3 only replicates the last partial column, so a caller passing
    // w > nx + 1 (or h > ny + 1) would leave intermediate columns/rows
    // unfilled. Reject such inputs explicitly instead of producing a
    // partially-filled map.
    if nx == 0 || ny == 0 || nx > w || ny > h || w > nx + 1 || h > ny + 1 {
        return Err(FilterError::InvalidParameters(format!(
            "fill_map_holes: expected nx ∈ {{w, w-1}} and ny ∈ {{h, h-1}} \
             (nx={nx}, ny={ny}, w={w}, h={h})"
        )));
    }
    fill_map_holes_inner(pix, nx, ny)
}

/// Generate inverted background map for normalization.
///
/// C版: `pixGetInvBackgroundMap()` in `adaptmap.c`
///
/// Computes multiplication factors `(256 * bg_val) / map_val` for each tile.
/// The resulting map is used by `apply_inv_background_gray_map()` to normalize.
///
/// # Input
/// - `pix`: 8 bpp grayscale, **non-colormapped**, with `width >= 5` and
///   `height >= 5` (matches the C contract; out-of-spec inputs return
///   `FilterError::UnsupportedDepth` or `FilterError::InvalidParameters`).
///
/// # Output
/// - 16 bpp `Pix` of the same dimensions as `pix`, holding the inverse
///   factors (range 0..=65535).
pub fn get_inv_background_map(
    pix: &Pix,
    bg_val: u32,
    smooth_x: u32,
    smooth_y: u32,
) -> FilterResult<Pix> {
    get_inv_background_map_inner(pix, bg_val, smooth_x, smooth_y)
}

/// Apply inverted background map to a grayscale image.
///
/// C版: `pixApplyInvBackgroundGrayMap()` in `adaptmap.c`
///
/// For each tile, multiplies pixel values by the corresponding factor
/// from the inverted map: `output = (input * factor) / 256`.
///
/// # Input
/// - `pix`: 8 bpp grayscale.
/// - `inv_map`: **16 bpp** factor map produced by
///   [`get_inv_background_map`]. Passing any other depth is rejected
///   with `FilterError::UnsupportedDepth`.
pub fn apply_inv_background_gray_map(
    pix: &Pix,
    inv_map: &Pix,
    tile_w: u32,
    tile_h: u32,
) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    if inv_map.depth() != PixelDepth::Bit16 {
        return Err(FilterError::UnsupportedDepth {
            expected: "16 bpp inv_map (use get_inv_background_map)",
            actual: inv_map.depth().bits(),
        });
    }
    apply_inv_background_gray_map_inner(pix, inv_map, tile_w, tile_h)
}

/// Apply inverted background maps to a 32bpp RGB image.
///
/// C版: `pixApplyInvBackgroundRGBMap()` in `adaptmap.c`
///
/// Applies separate inverted maps to each channel, then recombines.
///
/// # Input
/// - `pix`: 32 bpp RGB.
/// - `inv_map_r`/`inv_map_g`/`inv_map_b`: **16 bpp** factor maps produced
///   by [`get_inv_background_map`]. Any other depth returns
///   `FilterError::UnsupportedDepth`.
pub fn apply_inv_background_rgb_map(
    pix: &Pix,
    inv_map_r: &Pix,
    inv_map_g: &Pix,
    inv_map_b: &Pix,
    tile_w: u32,
    tile_h: u32,
) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32 bpp",
            actual: pix.depth().bits(),
        });
    }
    for (channel, inv_map) in [
        ("inv_map_r", inv_map_r),
        ("inv_map_g", inv_map_g),
        ("inv_map_b", inv_map_b),
    ] {
        if inv_map.depth() != PixelDepth::Bit16 {
            return Err(FilterError::InvalidParameters(format!(
                "{channel}: expected 16 bpp inv map (use get_inv_background_map), \
                 got {} bpp",
                inv_map.depth().bits()
            )));
        }
    }
    let (pixr, pixg, pixb) = extract_rgb_channels(pix)?;
    let result_r = apply_inv_background_gray_map_inner(&pixr, inv_map_r, tile_w, tile_h)?;
    let result_g = apply_inv_background_gray_map_inner(&pixg, inv_map_g, tile_w, tile_h)?;
    let result_b = apply_inv_background_gray_map_inner(&pixb, inv_map_b, tile_w, tile_h)?;
    combine_rgb_channels(&result_r, &result_g, &result_b, pix.spp())
}

/// Extract inverted background map array for a grayscale image.
///
/// C版: `pixBackgroundNormGrayArray()` in `adaptmap.c`
///
/// Convenience function that computes the background gray map, inverts it,
/// and returns the inverted map ready for application.
pub fn background_norm_gray_array(pix: &Pix, options: &BackgroundNormOptions) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    let o = options;
    let bg_map = get_background_gray_map_inner(
        pix,
        o.tile_width,
        o.tile_height,
        o.fg_threshold,
        o.min_count,
    )?;
    get_inv_background_map_inner(&bg_map, o.bg_val, o.smooth_x, o.smooth_y)
}

/// Extract inverted background map arrays for an RGB image.
///
/// C版: `pixBackgroundNormRGBArrays()` in `adaptmap.c`
///
/// Returns inverted maps for each channel.
pub fn background_norm_rgb_arrays(
    pix: &Pix,
    options: &BackgroundNormOptions,
) -> FilterResult<(Pix, Pix, Pix)> {
    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32 bpp",
            actual: pix.depth().bits(),
        });
    }
    let (pixr, pixg, pixb) = extract_rgb_channels(pix)?;
    let o = options;
    let inv_r = {
        let bg = get_background_gray_map_inner(
            &pixr,
            o.tile_width,
            o.tile_height,
            o.fg_threshold,
            o.min_count,
        )?;
        get_inv_background_map_inner(&bg, o.bg_val, o.smooth_x, o.smooth_y)?
    };
    let inv_g = {
        let bg = get_background_gray_map_inner(
            &pixg,
            o.tile_width,
            o.tile_height,
            o.fg_threshold,
            o.min_count,
        )?;
        get_inv_background_map_inner(&bg, o.bg_val, o.smooth_x, o.smooth_y)?
    };
    let inv_b = {
        let bg = get_background_gray_map_inner(
            &pixb,
            o.tile_width,
            o.tile_height,
            o.fg_threshold,
            o.min_count,
        )?;
        get_inv_background_map_inner(&bg, o.bg_val, o.smooth_x, o.smooth_y)?
    };
    Ok((inv_r, inv_g, inv_b))
}

/// Clean image background to white.
///
/// C版: `pixCleanBackgroundToWhite()` in `adaptmap.c`
///
/// Normalizes background using default parameters (bg_val=200), then
/// thresholds: pixels >= 180 are set to white (255).
pub fn clean_background_to_white(
    pix: &Pix,
    _mask: Option<&Pix>,
    _pixg: Option<&Pix>,
) -> FilterResult<Pix> {
    let normalized = background_norm_simple(pix)?;
    let w = normalized.width();
    let h = normalized.height();

    match normalized.depth() {
        PixelDepth::Bit8 => {
            let mut out = normalized.to_mut();
            for y in 0..h {
                for x in 0..w {
                    let val = out.get_pixel_unchecked(x, y);
                    if val >= 180 {
                        out.set_pixel_unchecked(x, y, 255);
                    }
                }
            }
            Ok(out.into())
        }
        PixelDepth::Bit32 => {
            let mut out = normalized.to_mut();
            for y in 0..h {
                for x in 0..w {
                    let pixel = out.get_pixel_unchecked(x, y);
                    let (r, g, b, _a) = pixel::extract_rgba(pixel);
                    let nr = if r >= 180 { 255 } else { r };
                    let ng = if g >= 180 { 255 } else { g };
                    let nb = if b >= 180 { 255 } else { b };
                    out.set_pixel_unchecked(x, y, pixel::compose_rgb(nr, ng, nb));
                }
            }
            Ok(out.into())
        }
        _ => Err(FilterError::UnsupportedDepth {
            expected: "8 or 32 bpp",
            actual: pix.depth().bits(),
        }),
    }
}

// ============================================================================
// Internal: Background map generation
// ============================================================================

/// Internal background map generation (shared by public and private callers)
fn get_background_gray_map_inner(
    pix: &Pix,
    tile_width: u32,
    tile_height: u32,
    fg_threshold: u32,
    min_count: u32,
) -> FilterResult<Pix> {
    use crate::color::threshold::threshold_to_binary;
    use crate::morph::sequence::morph_sequence;

    let w = pix.width();
    let h = pix.height();

    // Validate inputs that internal callers do not pre-check.
    if tile_width == 0 || tile_height == 0 {
        return Err(FilterError::InvalidParameters(format!(
            "tile dimensions must be non-zero (tile_width={tile_width}, tile_height={tile_height})"
        )));
    }
    if fg_threshold > 255 {
        return Err(FilterError::InvalidParameters(format!(
            "fg_threshold must be in 0..=255 (got {fg_threshold})"
        )));
    }

    // Build the dilated foreground mask `pixf` exactly as C does:
    //   pixb = pixThresholdToBinary(pixs, fg_threshold)
    //   pixf = pixMorphSequence(pixb, "d7.1 + d1.7", 0)
    // The dilation widens the fg region so that text-edge pixels (which
    // sit just outside the strict <fg_threshold band) are also excluded
    // from the per-tile background average. Without this step the Rust
    // map disagrees with C by tens of percent of pixels.
    let thresh_u8 = fg_threshold as u8;
    // Preserve the underlying core error if threshold_to_binary fails for
    // a structural reason (e.g. allocation), and surface other color-side
    // errors with a descriptive message rather than dropping their type.
    let pixb = threshold_to_binary(pix, thresh_u8).map_err(|e| match e {
        crate::color::ColorError::Core(core) => FilterError::Core(core),
        other => FilterError::InvalidParameters(format!("threshold_to_binary: {other}")),
    })?;
    let pixf = morph_sequence(&pixb, "d7.1 + d1.7")?;

    // Calculate map dimensions
    let map_w = w.div_ceil(tile_width);
    let map_h = h.div_ceil(tile_height);

    // Create the background map
    let map_pix = Pix::new(map_w, map_h, PixelDepth::Bit8)?;
    let mut map_mut = map_pix.try_into_mut().unwrap();

    // Number of complete tiles
    let nx = w / tile_width;
    let ny = h / tile_height;
    if nx == 0 || ny == 0 {
        return Err(FilterError::InvalidParameters(format!(
            "get_background_gray_map: tile size larger than image \
             (w={w}, h={h}, tile_width={tile_width}, tile_height={tile_height})"
        )));
    }

    // Process each complete tile
    for ty in 0..ny {
        for tx in 0..nx {
            let tile_x = tx * tile_width;
            let tile_y = ty * tile_height;

            // u64 accumulators tolerate any tile size. The binding
            // constraint is the per-channel u8 *sum*: a u32 accumulator
            // overflows around ~16.8M sampled pixels per tile (u32_max/255).
            // `count` itself wouldn't overflow until ~4.3B samples, but
            // we keep both at u64 so the divide doesn't need a cast back.
            let mut sum: u64 = 0;
            let mut count: u64 = 0;

            // Accumulate non-foreground pixels in this tile (matches C:
            // GET_DATA_BIT(linef + ..., delx + m) == 0).
            for y in tile_y..(tile_y + tile_height) {
                for x in tile_x..(tile_x + tile_width) {
                    if pixf.get_pixel_unchecked(x, y) == 0 {
                        sum += pix.get_pixel_unchecked(x, y) as u64;
                        count += 1;
                    }
                }
            }

            // Set map value if we have enough background pixels
            if count >= min_count as u64 {
                let avg = (sum / count) as u32;
                map_mut.set_pixel_unchecked(tx, ty, avg);
            }
            // Otherwise leave as 0 (will be filled later)
        }
    }

    // Convert to immutable for hole filling
    let map_pix = map_mut.into();

    // Fill holes in the map (tiles with value 0)
    fill_map_holes_inner(&map_pix, nx, ny)
}

/// Generate background maps for each RGB channel from a single 32 bpp
/// input. Mirrors C `pixGetBackgroundRGBMap` (adaptmap.c:1071).
///
/// Crucially this differs from running `get_background_gray_map_inner`
/// per channel: a **single** foreground mask is built from a fast
/// grayscale conversion of the input (`pixConvertRGBToGrayFast`) and
/// shared across all three channels, and the per-tile loop accumulates
/// R, G, B sums together. The per-channel approach the previous Rust
/// port used produced different fg masks for each channel and
/// disagreed with C output materially.
fn get_background_rgb_map_inner(
    pix: &Pix,
    tile_width: u32,
    tile_height: u32,
    fg_threshold: u32,
    min_count: u32,
) -> FilterResult<(Pix, Pix, Pix)> {
    use crate::color::threshold::threshold_to_binary;
    use crate::morph::sequence::morph_sequence;

    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32 bpp",
            actual: pix.depth().bits(),
        });
    }
    if tile_width == 0 || tile_height == 0 {
        return Err(FilterError::InvalidParameters(format!(
            "tile dimensions must be non-zero (tile_width={tile_width}, \
             tile_height={tile_height})"
        )));
    }
    if fg_threshold > 255 {
        return Err(FilterError::InvalidParameters(format!(
            "fg_threshold must be in 0..=255 (got {fg_threshold})"
        )));
    }

    let w = pix.width();
    let h = pix.height();

    // Shared fg mask: gray-fast → threshold → dilate, exactly as C does.
    let pixgc = pix.convert_rgb_to_gray_fast()?;
    let thresh_u8 = fg_threshold as u8;
    let pixb = threshold_to_binary(&pixgc, thresh_u8).map_err(|e| match e {
        crate::color::ColorError::Core(core) => FilterError::Core(core),
        other => FilterError::InvalidParameters(format!("threshold_to_binary: {other}")),
    })?;
    let pixf = morph_sequence(&pixb, "d7.1 + d1.7")?;

    let map_w = w.div_ceil(tile_width);
    let map_h = h.div_ceil(tile_height);
    let pixmr = Pix::new(map_w, map_h, PixelDepth::Bit8)?;
    let pixmg = Pix::new(map_w, map_h, PixelDepth::Bit8)?;
    let pixmb = Pix::new(map_w, map_h, PixelDepth::Bit8)?;
    let mut mr_mut = pixmr.try_into_mut().unwrap();
    let mut mg_mut = pixmg.try_into_mut().unwrap();
    let mut mb_mut = pixmb.try_into_mut().unwrap();

    let nx = w / tile_width;
    let ny = h / tile_height;
    if nx == 0 || ny == 0 {
        return Err(FilterError::InvalidParameters(format!(
            "get_background_rgb_map: tile size larger than image \
             (w={w}, h={h}, tile_width={tile_width}, tile_height={tile_height})"
        )));
    }

    for ty in 0..ny {
        for tx in 0..nx {
            let tile_x = tx * tile_width;
            let tile_y = ty * tile_height;

            // u64 accumulators tolerate any tile size. The binding
            // constraint is the per-channel u8 *sum*: a u32 accumulator
            // overflows around ~16.8M sampled pixels per tile (u32_max/255).
            // `count` itself wouldn't overflow until ~4.3B samples, but
            // we keep both at u64 so the divide doesn't need a cast back.
            let mut rsum: u64 = 0;
            let mut gsum: u64 = 0;
            let mut bsum: u64 = 0;
            let mut count: u64 = 0;

            for y in tile_y..(tile_y + tile_height) {
                for x in tile_x..(tile_x + tile_width) {
                    if pixf.get_pixel_unchecked(x, y) == 0 {
                        let pixel = pix.get_pixel_unchecked(x, y) as u64;
                        // C reads `(pixel >> 24)` for R, `(pixel >> 16) & 0xff`
                        // for G, `(pixel >> 8) & 0xff` for B (alpha in low 8).
                        rsum += (pixel >> 24) & 0xff;
                        gsum += (pixel >> 16) & 0xff;
                        bsum += (pixel >> 8) & 0xff;
                        count += 1;
                    }
                }
            }

            if count >= min_count as u64 {
                mr_mut.set_pixel_unchecked(tx, ty, (rsum / count) as u32);
                mg_mut.set_pixel_unchecked(tx, ty, (gsum / count) as u32);
                mb_mut.set_pixel_unchecked(tx, ty, (bsum / count) as u32);
            }
        }
    }

    let pixmr: Pix = mr_mut.into();
    let pixmg: Pix = mg_mut.into();
    let pixmb: Pix = mb_mut.into();

    let pixmr = fill_map_holes_inner(&pixmr, nx, ny)?;
    let pixmg = fill_map_holes_inner(&pixmg, nx, ny)?;
    let pixmb = fill_map_holes_inner(&pixmb, nx, ny)?;

    Ok((pixmr, pixmg, pixmb))
}

/// Fill holes (zero values) in the map by propagating from neighbors
fn fill_map_holes_inner(pix: &Pix, nx: u32, ny: u32) -> FilterResult<Pix> {
    let w = pix.width();
    let h = pix.height();

    let out_pix = pix.deep_clone();
    let mut out_mut = out_pix.try_into_mut().unwrap();

    let nx_idx = nx as usize;
    let mut column_has_data = vec![false; nx_idx];
    let mut nmiss: u32 = 0;

    // Phase 1: vertical fill within each tile column.
    // Search for the first non-zero pixel in rows 0..ny (the data origin
    // is bounded to the full-tile region). Then replicate that value up
    // to row 0 and propagate the most-recent valid value downward through
    // the entire column height (0..h) so partial-tile rows are filled too.
    for j in 0..nx {
        let mut first: Option<u32> = None;
        for i in 0..ny {
            if out_mut.get_pixel_unchecked(j, i) != 0 {
                first = Some(i);
                break;
            }
        }
        match first {
            None => {
                column_has_data[j as usize] = false;
                nmiss += 1;
            }
            Some(y) => {
                column_has_data[j as usize] = true;
                let val = out_mut.get_pixel_unchecked(j, y);
                for i in 0..y {
                    out_mut.set_pixel_unchecked(j, i, val);
                }
                let mut lastval = out_mut.get_pixel_unchecked(j, 0);
                for i in 1..h {
                    let v = out_mut.get_pixel_unchecked(j, i);
                    if v == 0 {
                        out_mut.set_pixel_unchecked(j, i, lastval);
                    } else {
                        lastval = v;
                    }
                }
            }
        }
    }

    if nmiss == nx {
        return Err(FilterError::InvalidParameters(
            "fill_map_holes: no data in any column".to_string(),
        ));
    }

    // Phase 2: replicate missing columns from the nearest valid column.
    if nmiss > 0 {
        let goodcol = (0..nx)
            .find(|&j| column_has_data[j as usize])
            .expect("nmiss < nx implies at least one valid column");
        // Backward fill: every column to the left of goodcol copies its
        // right neighbor (which has just been filled).
        for j in (0..goodcol).rev() {
            for i in 0..h {
                let v = out_mut.get_pixel_unchecked(j + 1, i);
                out_mut.set_pixel_unchecked(j, i, v);
            }
        }
        // Forward fill: empty columns copy their already-valid left neighbor.
        for j in (goodcol + 1)..nx {
            if !column_has_data[j as usize] {
                for i in 0..h {
                    let v = out_mut.get_pixel_unchecked(j - 1, i);
                    out_mut.set_pixel_unchecked(j, i, v);
                }
            }
        }
    }

    // Phase 3: replicate the last partial-tile column when the map is
    // wider than the full-tile region.
    if w > nx {
        for i in 0..h {
            let v = out_mut.get_pixel_unchecked(w - 2, i);
            out_mut.set_pixel_unchecked(w - 1, i, v);
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Internal: Inverted background map
// ============================================================================

/// Generate inverted background map for normalization
///
/// The inverted map contains multiplication factors such that:
/// output = (input * factor) / 256
fn get_inv_background_map_inner(
    pix: &Pix,
    bg_val: u32,
    smooth_x: u32,
    smooth_y: u32,
) -> FilterResult<Pix> {
    use crate::filter::block_conv::blockconv;

    let w = pix.width();
    let h = pix.height();

    // C contract (adaptmap.c:1865-1869): pixs must be 8 bpp non-colormapped
    // and at least 5x5. Mirror the same checks but report depth and
    // colormap failures separately so diagnostics are not misleading.
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    if pix.colormap().is_some() {
        return Err(FilterError::InvalidParameters(
            "get_inv_background_map: pix must be non-colormapped".to_string(),
        ));
    }
    if w < 5 || h < 5 {
        return Err(FilterError::InvalidParameters(format!(
            "get_inv_background_map: w/h must be >= 5 (got {w}x{h})"
        )));
    }

    // C: pixsm = pixBlockconv(pixs, smoothx, smoothy);
    // pixBlockconv treats wc=0 || hc=0 as a no-op copy. Rust's `blockconv`
    // forwards 8 bpp input to `blockconv_gray`, which documents the same
    // no-op behavior when either kernel half-width is zero.
    let smoothed = blockconv(pix, smooth_x, smooth_y)?;

    // C: pixd = pixCreate(w, h, 16); per-pixel val16 = (256 * bgval) / val
    // (or bgval/2 for the warned-but-can't-happen 0 case after smoothing).
    let out_pix = Pix::new(w, h, PixelDepth::Bit16)?;
    let mut out_mut = out_pix.try_into_mut().unwrap();

    // Compute numerator in u64 to avoid overflow when bg_val is large
    // (256 * u32::MAX would overflow u32). C uses l_int32 so practical
    // bg_val never exceeds 2^31-1, and u64 covers that range safely.
    let numerator = 256u64 * bg_val as u64;
    for y in 0..h {
        for x in 0..w {
            let val = smoothed.get_pixel_unchecked(x, y);
            let factor = if val > 0 {
                (numerator / val as u64).min(65535) as u32
            } else {
                // C path is "L_WARNING smoothed bg has 0 pixel; val16 = bgval/2".
                // Mirror the warning's value directly without going through
                // checked_div so an overflow in `numerator` does NOT route
                // here.
                bg_val / 2
            };
            out_mut.set_pixel_unchecked(x, y, factor.min(65535));
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Internal: Apply background map
// ============================================================================

/// Apply inverted background map to grayscale image
fn apply_inv_background_gray_map_inner(
    pix: &Pix,
    inv_map: &Pix,
    tile_width: u32,
    tile_height: u32,
) -> FilterResult<Pix> {
    let w = pix.width();
    let h = pix.height();
    let map_w = inv_map.width();
    let map_h = inv_map.height();

    let out_pix = Pix::new(w, h, PixelDepth::Bit8)?;
    let mut out_mut = out_pix.try_into_mut().unwrap();

    for ty in 0..map_h {
        for tx in 0..map_w {
            // Get the multiplication factor for this tile
            let factor = inv_map.get_pixel_unchecked(tx, ty);

            // Calculate tile boundaries
            let x_start = tx * tile_width;
            let y_start = ty * tile_height;
            let x_end = (x_start + tile_width).min(w);
            let y_end = (y_start + tile_height).min(h);

            // Apply factor to each pixel in the tile
            for y in y_start..y_end {
                for x in x_start..x_end {
                    let val = pix.get_pixel_unchecked(x, y);
                    let normalized = (val * factor) / 256;
                    out_mut.set_pixel_unchecked(x, y, normalized.min(255));
                }
            }
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Internal: RGB channel operations
// ============================================================================

/// Extract R, G, B channels from a 32bpp image
fn extract_rgb_channels(pix: &Pix) -> FilterResult<(Pix, Pix, Pix)> {
    let w = pix.width();
    let h = pix.height();

    let pix_r = Pix::new(w, h, PixelDepth::Bit8)?;
    let pix_g = Pix::new(w, h, PixelDepth::Bit8)?;
    let pix_b = Pix::new(w, h, PixelDepth::Bit8)?;

    let mut r_mut = pix_r.try_into_mut().unwrap();
    let mut g_mut = pix_g.try_into_mut().unwrap();
    let mut b_mut = pix_b.try_into_mut().unwrap();

    for y in 0..h {
        for x in 0..w {
            let pixel = pix.get_pixel_unchecked(x, y);
            let (r, g, b, _) = pixel::extract_rgba(pixel);
            r_mut.set_pixel_unchecked(x, y, r as u32);
            g_mut.set_pixel_unchecked(x, y, g as u32);
            b_mut.set_pixel_unchecked(x, y, b as u32);
        }
    }

    Ok((r_mut.into(), g_mut.into(), b_mut.into()))
}

/// Combine R, G, B channels into a 32bpp image
fn combine_rgb_channels(pix_r: &Pix, pix_g: &Pix, pix_b: &Pix, spp: u32) -> FilterResult<Pix> {
    let w = pix_r.width();
    let h = pix_r.height();

    let out_pix = Pix::new(w, h, PixelDepth::Bit32)?;
    let mut out_mut = out_pix.try_into_mut().unwrap();
    out_mut.set_spp(spp);

    for y in 0..h {
        for x in 0..w {
            let r = pix_r.get_pixel_unchecked(x, y) as u8;
            let g = pix_g.get_pixel_unchecked(x, y) as u8;
            let b = pix_b.get_pixel_unchecked(x, y) as u8;
            let pixel = pixel::compose_rgb(r, g, b);
            out_mut.set_pixel_unchecked(x, y, pixel);
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Public API: Contrast normalization
// ============================================================================

/// Local contrast normalization with default parameters
///
/// Adaptively expands the dynamic range in each tile to the full 8-bit range.
///
/// # Arguments
/// * `pix` - Input 8bpp grayscale image
///
/// # Returns
/// Contrast-normalized image
pub fn contrast_norm_simple(pix: &Pix) -> FilterResult<Pix> {
    contrast_norm(pix, &ContrastNormOptions::default())
}

/// Local contrast normalization with custom parameters
///
/// For each tile, expands the local dynamic range so that the minimum
/// value maps to 0 and the maximum value maps to 255.
///
/// # Arguments
/// * `pix` - Input 8bpp grayscale image
/// * `options` - Normalization parameters
///
/// # Returns
/// Contrast-normalized image
pub fn contrast_norm(pix: &Pix, options: &ContrastNormOptions) -> FilterResult<Pix> {
    // Decode colormap up front (see comment in background_norm).
    if pix.colormap().is_some() {
        let decoded = pix.remove_colormap(crate::core::pix::RemoveColormapTarget::ToGrayscale)?;
        return contrast_norm(&decoded, options);
    }

    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }

    // Validate parameters
    if options.tile_width < 5 || options.tile_height < 5 {
        return Err(FilterError::InvalidParameters(
            "tile dimensions must be >= 5".to_string(),
        ));
    }
    if options.smooth_x > 8 || options.smooth_y > 8 {
        return Err(FilterError::InvalidParameters(
            "smooth parameters must be <= 8".to_string(),
        ));
    }

    // Get min/max tiles
    let (pix_min, pix_max) = min_max_tiles(
        pix,
        options.tile_width,
        options.tile_height,
        options.min_diff,
        options.smooth_x,
        options.smooth_y,
    )?;

    // Apply linear TRC tiled
    linear_trc_tiled(
        pix,
        options.tile_width,
        options.tile_height,
        &pix_min,
        &pix_max,
    )
}

// ============================================================================
// Internal: Contrast normalization helpers
// ============================================================================

/// Compute per-tile min/max maps for `pixContrastNorm` / `pixMinMaxTiles`.
///
/// Mirrors C `pixMinMaxTiles` (adaptmap.c:2655) exactly:
///
/// 1. `pixScaleGrayMinMax` → per-tile min/max maps of size `(W/sx, H/sy)`
/// 2. `pixExtendByReplication(., 1, 1)` to add 1 row/col on the right/bottom
///    (so the map has one extra cell to cover partial-tile edges)
/// 3. `add_constant(1)` so that 0 is reserved as a "this tile is a hole"
///    sentinel even when the original min was 0
/// 4. `set_low_contrast` zeros tile pairs where `|max - min| < min_diff`
/// 5. `fill_map_holes_inner` fills the holes (sentinel zeros)
/// 6. optional `blockconv` smoothing (matches C `pixBlockconv`)
fn min_max_tiles(
    pix: &Pix,
    tile_width: u32,
    tile_height: u32,
    min_diff: u32,
    smooth_x: u32,
    smooth_y: u32,
) -> FilterResult<(Pix, Pix)> {
    use crate::filter::block_conv::blockconv;
    use crate::filter::rank::{MinMaxOp, scale_gray_min_max};

    // Step 1: per-tile min and max via scale_gray_min_max (C: pixScaleGrayMinMax).
    let pix_min = scale_gray_min_max(pix, tile_width, tile_height, MinMaxOp::Min)?;
    let pix_max = scale_gray_min_max(pix, tile_width, tile_height, MinMaxOp::Max)?;

    // Step 2: extend right/bottom by 1 cell, matching C `pixExtendByReplication(., 1, 1)`
    // (note: Rust's public `extend_by_replication` extends both sides, so we
    // inline a C-equivalent extension here).
    let pix_min = extend_right_bottom_by_one(&pix_min)?;
    let pix_max = extend_right_bottom_by_one(&pix_max)?;
    let map_w = pix_min.width();
    let map_h = pix_min.height();

    // Step 3: bias by +1 so 0 can serve as a hole sentinel.
    let pix_min = pix_min.add_constant(1)?;
    let pix_max = pix_max.add_constant(1)?;

    // Step 4: zero tile pairs whose contrast is below min_diff.
    let (pix_min, pix_max) = set_low_contrast(pix_min, pix_max, min_diff)?;

    // Step 5: fill the holes.
    let pix_min = fill_map_holes_inner(&pix_min, map_w, map_h)?;
    let pix_max = fill_map_holes_inner(&pix_max, map_w, map_h)?;

    // Step 6: smooth (matches C `pixBlockconv`). C clamps smooth half-widths
    // to (map_w-1)/2 and (map_h-1)/2 to keep the kernel inside the map.
    //
    // The `>` is OR (not AND) deliberately, mirroring C's
    // `if (smoothx > 0 || smoothy > 0)`. When only one half-width is zero,
    // `blockconv`/`pixBlockconv` falls back to a copy (1×N or N×1 kernels
    // are documented as no-ops on both sides), so behavior matches C.
    let pix_min = if smooth_x > 0 || smooth_y > 0 {
        let sx = smooth_x.min((map_w - 1) / 2);
        let sy = smooth_y.min((map_h - 1) / 2);
        blockconv(&pix_min, sx, sy)?
    } else {
        pix_min
    };
    let pix_max = if smooth_x > 0 || smooth_y > 0 {
        let sx = smooth_x.min((map_w - 1) / 2);
        let sy = smooth_y.min((map_h - 1) / 2);
        blockconv(&pix_max, sx, sy)?
    } else {
        pix_max
    };

    Ok((pix_min, pix_max))
}

/// Replicate the right column and bottom row of an 8 bpp Pix once,
/// producing a `(w + 1) × (h + 1)` Pix. Mirrors C
/// `pixExtendByReplication(pix, 1, 1)` exactly (note: Rust's public
/// `extend_by_replication` extends both sides, so it cannot be reused here).
///
/// Rejects 8 bpp colormapped inputs explicitly: `Pix::new` would otherwise
/// silently produce a non-colormapped output, treating palette indices as
/// gray values downstream (the same trap `scale_gray_min_max` calls out).
fn extend_right_bottom_by_one(pix: &Pix) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    if pix.colormap().is_some() {
        return Err(FilterError::InvalidParameters(
            "extend_right_bottom_by_one: colormapped input not supported; \
             remove the colormap first"
                .to_string(),
        ));
    }
    let w = pix.width();
    let h = pix.height();
    let new_w = w
        .checked_add(1)
        .ok_or_else(|| FilterError::InvalidParameters("width + 1 overflow".into()))?;
    let new_h = h
        .checked_add(1)
        .ok_or_else(|| FilterError::InvalidParameters("height + 1 overflow".into()))?;
    let out = Pix::new(new_w, new_h, PixelDepth::Bit8)?;
    let mut out_mut = out.try_into_mut().unwrap();
    for y in 0..h {
        for x in 0..w {
            out_mut.set_pixel_unchecked(x, y, pix.get_pixel_unchecked(x, y));
        }
    }
    // Right column: replicate column w-1.
    for y in 0..h {
        let v = pix.get_pixel_unchecked(w - 1, y);
        out_mut.set_pixel_unchecked(w, y, v);
    }
    // Bottom row + bottom-right corner: replicate row h-1 (including the
    // newly written right column).
    for x in 0..(w + 1) {
        let v = out_mut.get_pixel_unchecked(x, h - 1);
        out_mut.set_pixel_unchecked(x, h, v);
    }
    Ok(out_mut.into())
}

/// C-aligned `pixSetLowContrast` (adaptmap.c:2744).
///
/// First scans both maps; if no tile pair has an absolute difference
/// `>= min_diff`, returns `FilterError::InvalidParameters` with a clear
/// message ("input has no tile pair with sufficient contrast"). C clears
/// the maps and returns 1 in this case, leaving the caller to surface
/// the failure later as a generic "no data in any column" error from
/// `pixFillMapHoles`; we surface the underlying cause directly so callers
/// see why `contrast_norm` rejected their input.
///
/// Otherwise zeros tile pairs whose absolute difference is `< min_diff`,
/// matching C's per-cell behavior bit-for-bit.
///
/// `min_diff > 254` is a no-op (returns the maps untouched). C bails
/// early there because every 8 bpp tile pair would be cleared, which is
/// nonsense input.
fn set_low_contrast(pix_min: Pix, pix_max: Pix, min_diff: u32) -> FilterResult<(Pix, Pix)> {
    let w = pix_min.width();
    let h = pix_min.height();
    if w != pix_max.width() || h != pix_max.height() {
        return Err(FilterError::InvalidParameters(
            "set_low_contrast: pix_min and pix_max must have equal dimensions".to_string(),
        ));
    }
    if min_diff > 254 {
        return Ok((pix_min, pix_max));
    }

    let mut found = false;
    'outer: for y in 0..h {
        for x in 0..w {
            let v1 = pix_min.get_pixel_unchecked(x, y) as i32;
            let v2 = pix_max.get_pixel_unchecked(x, y) as i32;
            if (v1 - v2).unsigned_abs() >= min_diff {
                found = true;
                break 'outer;
            }
        }
    }

    if !found {
        return Err(FilterError::InvalidParameters(format!(
            "set_low_contrast: no tile pair has |max - min| >= {min_diff}; \
             input is below the requested contrast threshold"
        )));
    }

    // Convert each owned Pix into a mutable handle. `try_into_mut()`
    // returns the Pix back as `Err` when the Arc refcount > 1 (it does
    // not copy-on-write); fall back to `to_mut()` in that rare case so
    // we always make progress, but the common single-owner path is
    // zero-copy.
    let mut min_mut = pix_min.try_into_mut().unwrap_or_else(|p| p.to_mut());
    let mut max_mut = pix_max.try_into_mut().unwrap_or_else(|p| p.to_mut());
    for y in 0..h {
        for x in 0..w {
            let v1 = min_mut.get_pixel_unchecked(x, y) as i32;
            let v2 = max_mut.get_pixel_unchecked(x, y) as i32;
            if (v1 - v2).unsigned_abs() < min_diff {
                min_mut.set_pixel_unchecked(x, y, 0);
                max_mut.set_pixel_unchecked(x, y, 0);
            }
        }
    }

    Ok((min_mut.into(), max_mut.into()))
}

/// Apply linear TRC tiled to expand contrast.
///
/// Mirrors C `pixLinearTRCTiled` (adaptmap.c:2825). The min/max maps are
/// expected to come from `min_max_tiles` / `pixMinMaxTiles`, where every
/// cell has been biased by `+1` (so 0 can be reserved as a hole sentinel)
/// **and then clipped to `255`** by `Pix::add_constant`. We do not undo
/// that bias here: C uses the biased map values directly when computing
/// `sval = val - minval` and `diff = maxval - minval`, and we intentionally
/// follow the same biased-and-clipped maps so the LUT inputs and outputs
/// match C bit-for-bit. (Note `diff` is *not* invariant when a tile's
/// `maxval` saturates at 255 from the `+1` clip — but that saturation is
/// part of C's contract here, so the resulting LUT shape matches.)
fn linear_trc_tiled(
    pix: &Pix,
    tile_width: u32,
    tile_height: u32,
    pix_min: &Pix,
    pix_max: &Pix,
) -> FilterResult<Pix> {
    let w = pix.width();
    let h = pix.height();
    let map_w = pix_min.width();
    let map_h = pix_min.height();

    let out_pix = pix.deep_clone();
    let mut out_mut = out_pix.try_into_mut().unwrap();

    // Lazy LUT cache, keyed by `diff = maxval - minval` (range 0..=255).
    let mut lut_cache: [Option<[u8; 256]>; 256] = [None; 256];

    for ty in 0..map_h {
        for tx in 0..map_w {
            let min_val = pix_min.get_pixel_unchecked(tx, ty);
            let max_val = pix_max.get_pixel_unchecked(tx, ty);

            if max_val <= min_val {
                // C `L_ERROR("shouldn't happen!")` and continues. We mirror
                // the silent-skip behavior so the rest of the image still
                // gets normalized.
                continue;
            }

            let diff = (max_val - min_val) as usize;

            let lut = if let Some(existing) = &lut_cache[diff] {
                existing
            } else {
                let mut new_lut = [0u8; 256];
                let factor = 255.0_f32 / diff as f32;
                // C iaaGetLinearTRC: ia[i] = (l_int32)(factor * i + 0.5)
                // for i in 0..=diff; ia[i] = 255 for i in (diff+1)..256.
                for (i, slot) in new_lut.iter_mut().enumerate().take(diff + 1) {
                    *slot = ((factor * i as f32) + 0.5).min(255.0) as u8;
                }
                for slot in new_lut.iter_mut().skip(diff + 1) {
                    *slot = 255;
                }
                lut_cache[diff] = Some(new_lut);
                lut_cache[diff].as_ref().unwrap()
            };

            let x_start = tx * tile_width;
            let y_start = ty * tile_height;
            let x_end = (x_start + tile_width).min(w);
            let y_end = (y_start + tile_height).min(h);

            for y in y_start..y_end {
                for x in x_start..x_end {
                    let val = pix.get_pixel_unchecked(x, y);
                    // C: sval = val - minval; sval = L_MAX(0, sval); ia[sval]
                    // (the LUT is sized for input 0..=255, and excess inputs
                    // get clamped to 255 as in `iaaGetLinearTRC`).
                    let sval = val.saturating_sub(min_val) as usize;
                    let mapped = lut[sval.min(255)];
                    out_mut.set_pixel_unchecked(x, y, mapped as u32);
                }
            }
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Edge replication
// ============================================================================

/// Extend an image by replicating edge pixels.
///
/// C版: `pixExtendByReplication()` in `adaptmap.c`
///
/// Creates a new image with dimensions `(w + 2*extend_x, h + 2*extend_y)`.
/// The source image is placed at offset `(extend_x, extend_y)` and the borders
/// are filled by replicating edge pixels. Works for any pixel depth and
/// preserves colormaps.
pub fn extend_by_replication(pix: &Pix, extend_x: u32, extend_y: u32) -> FilterResult<Pix> {
    let w = pix.width();
    let h = pix.height();
    let depth = pix.depth();

    if extend_x == 0 && extend_y == 0 {
        return Ok(pix.deep_clone());
    }

    // Use checked arithmetic to prevent overflow
    let double_x = extend_x
        .checked_mul(2)
        .ok_or_else(|| FilterError::InvalidParameters("extend_x overflow".into()))?;
    let double_y = extend_y
        .checked_mul(2)
        .ok_or_else(|| FilterError::InvalidParameters("extend_y overflow".into()))?;
    let new_w = w
        .checked_add(double_x)
        .ok_or_else(|| FilterError::InvalidParameters("resulting width overflow".into()))?;
    let new_h = h
        .checked_add(double_y)
        .ok_or_else(|| FilterError::InvalidParameters("resulting height overflow".into()))?;

    let out_pix = Pix::new(new_w, new_h, depth)?;
    let mut out_mut = out_pix.try_into_mut().unwrap();
    out_mut.set_spp(pix.spp());

    // Preserve colormap if present
    if let Some(cmap) = pix.colormap() {
        let _ = out_mut.set_colormap(Some(cmap.clone()));
    }

    // Copy source image to center region
    for y in 0..h {
        for x in 0..w {
            let val = pix.get_pixel_unchecked(x, y);
            out_mut.set_pixel_unchecked(x + extend_x, y + extend_y, val);
        }
    }

    // Replicate left and right edges
    for y in 0..h {
        let left_val = pix.get_pixel_unchecked(0, y);
        let right_val = pix.get_pixel_unchecked(w - 1, y);
        for ex in 0..extend_x {
            out_mut.set_pixel_unchecked(ex, y + extend_y, left_val);
            out_mut.set_pixel_unchecked(extend_x + w + ex, y + extend_y, right_val);
        }
    }

    // Replicate top and bottom edges (including corners)
    for x in 0..new_w {
        let top_val = out_mut.get_pixel_unchecked(x, extend_y);
        let bottom_val = out_mut.get_pixel_unchecked(x, extend_y + h - 1);
        for ey in 0..extend_y {
            out_mut.set_pixel_unchecked(x, ey, top_val);
            out_mut.set_pixel_unchecked(x, extend_y + h + ey, bottom_val);
        }
    }

    Ok(out_mut.into())
}

// ============================================================================
// Morph-based background map extraction
// ============================================================================

/// Extract a grayscale background map using morphological closing.
///
/// C版: `pixGetBackgroundGrayMapMorph()` in `adaptmap.c`
///
/// This is an alternative to [`get_background_gray_map`] that uses
/// morphological closing (instead of tile-based averaging) to estimate the
/// background. The closing removes foreground features, leaving only the
/// background illumination pattern.
///
/// # Arguments
///
/// * `pix` - 8bpp grayscale image (no colormap)
/// * `_mask` - Reserved for future use (must be `None`)
/// * `reduction` - Downscaling factor for closing (2..=16)
/// * `size` - Size of square structuring element for closing (use odd number)
pub fn get_background_gray_map_morph(
    pix: &Pix,
    _mask: Option<&Pix>,
    reduction: u32,
    size: u32,
) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8bpp",
            actual: pix.depth().bits(),
        });
    }
    if pix.has_colormap() {
        return Err(FilterError::InvalidParameters(
            "colormapped images not supported".into(),
        ));
    }
    if !(2..=16).contains(&reduction) {
        return Err(FilterError::InvalidParameters(
            "reduction must be between 2 and 16".into(),
        ));
    }

    let scale = 1.0 / reduction as f32;

    // Downscale and apply morphological closing to estimate background
    let pix1 = crate::transform::scale_by_sampling(pix, scale, scale)?;
    let pix2 = crate::morph::close_gray(&pix1, size, size)?;
    let pix3 = extend_by_replication(&pix2, 1, 1)?;

    // Fill holes in the map
    let nx = pix.width() / reduction;
    let ny = pix.height() / reduction;
    let filled = fill_map_holes_inner(&pix3, nx, ny)?;

    Ok(filled)
}

/// Extract RGB background maps using morphological closing.
///
/// C版: `pixGetBackgroundRGBMapMorph()` in `adaptmap.c`
///
/// This is the RGB equivalent of [`get_background_gray_map_morph`]. Each
/// color channel is processed independently: the channel is extracted,
/// downscaled, closed, and then holes are filled.
///
/// # Arguments
///
/// * `pix` - 32bpp RGB image
/// * `_mask` - Reserved for future use (must be `None`)
/// * `reduction` - Downscaling factor for closing (2..=16)
/// * `size` - Size of square structuring element for closing (use odd number)
pub fn get_background_rgb_map_morph(
    pix: &Pix,
    _mask: Option<&Pix>,
    reduction: u32,
    size: u32,
) -> FilterResult<(Pix, Pix, Pix)> {
    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32bpp",
            actual: pix.depth().bits(),
        });
    }
    if !(2..=16).contains(&reduction) {
        return Err(FilterError::InvalidParameters(
            "reduction must be between 2 and 16".into(),
        ));
    }

    let nx = pix.width() / reduction;
    let ny = pix.height() / reduction;

    // Process each channel: extract, downscale, close, extend, fill holes
    let map_r =
        get_background_single_channel_morph(pix, reduction, size, nx, ny, pixel::RED_SHIFT)?;
    let map_g =
        get_background_single_channel_morph(pix, reduction, size, nx, ny, pixel::GREEN_SHIFT)?;
    let map_b =
        get_background_single_channel_morph(pix, reduction, size, nx, ny, pixel::BLUE_SHIFT)?;

    Ok((map_r, map_g, map_b))
}

/// Process a single color channel for morph-based background extraction.
///
/// Extracts the channel from a 32bpp image by subsampling, applies
/// morphological closing, extends by replication, and fills holes.
fn get_background_single_channel_morph(
    pix: &Pix,
    reduction: u32,
    size: u32,
    nx: u32,
    ny: u32,
    shift: u32,
) -> FilterResult<Pix> {
    let pix1 = scale_rgb_to_gray_fast(pix, reduction, shift)?;
    let pix2 = crate::morph::close_gray(&pix1, size, size)?;
    let pix3 = extend_by_replication(&pix2, 1, 1)?;
    fill_map_holes_inner(&pix3, nx, ny)
}

/// Fast downscaling of a single RGB channel to 8bpp grayscale.
///
/// Simultaneously subsamples by an integer factor and extracts
/// a single color component. Equivalent to C `pixScaleRGBToGrayFast()`.
fn scale_rgb_to_gray_fast(pix: &Pix, factor: u32, shift: u32) -> FilterResult<Pix> {
    let ws = pix.width();
    let hs = pix.height();
    let wd = ws / factor;
    let hd = hs / factor;

    if wd == 0 || hd == 0 {
        return Err(FilterError::InvalidParameters(
            "reduction factor too large for image size".into(),
        ));
    }

    let out = Pix::new(wd, hd, PixelDepth::Bit8)?;
    let mut out_mut = out.try_into_mut().unwrap();

    for y in 0..hd {
        let src_y = y * factor;
        for x in 0..wd {
            let src_x = x * factor;
            let pixel = pix.get_pixel_unchecked(src_x, src_y);
            let val = (pixel >> shift) & 0xff;
            out_mut.set_pixel_unchecked(x, y, val);
        }
    }

    Ok(out_mut.into())
}

/// Normalize image background using morphological closing.
///
/// C版: `pixBackgroundNormMorph()` in `adaptmap.c`
///
/// Top-level interface that maps the image so that the background
/// is near the target `bgval`. Uses morphological closing to
/// estimate the background, unlike [`background_norm`] which uses
/// tile-based averaging.
///
/// # Arguments
///
/// * `pix` - 8bpp grayscale or 32bpp RGB image
/// * `mask` - Reserved for future use (must be `None`)
/// * `reduction` - Downscaling factor for closing (2..=16)
/// * `size` - Size of square structuring element for closing (use odd number)
/// * `bgval` - Target background value (typically > 128)
pub fn background_norm_morph(
    pix: &Pix,
    mask: Option<&Pix>,
    reduction: u32,
    size: u32,
    bgval: u32,
) -> FilterResult<Pix> {
    let d = pix.depth();
    if d != PixelDepth::Bit8 && d != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 or 32 bpp",
            actual: d.bits(),
        });
    }
    if !(2..=16).contains(&reduction) {
        return Err(FilterError::InvalidParameters(
            "reduction must be between 2 and 16".into(),
        ));
    }

    if d == PixelDepth::Bit8 {
        let bg_map = get_background_gray_map_morph(pix, mask, reduction, size)?;
        let inv_map = get_inv_background_map_inner(&bg_map, bgval, 0, 0)?;
        apply_inv_background_gray_map_inner(pix, &inv_map, reduction, reduction)
    } else {
        // 32bpp RGB
        let (map_r, map_g, map_b) = get_background_rgb_map_morph(pix, mask, reduction, size)?;
        let inv_r = get_inv_background_map_inner(&map_r, bgval, 0, 0)?;
        let inv_g = get_inv_background_map_inner(&map_g, bgval, 0, 0)?;
        let inv_b = get_inv_background_map_inner(&map_b, bgval, 0, 0)?;
        apply_inv_background_rgb_map(pix, &inv_r, &inv_g, &inv_b, reduction, reduction)
    }
}

/// Extract the inverted grayscale background map array using morphological closing.
///
/// C版: `pixBackgroundNormGrayArrayMorph()` in `adaptmap.c`
///
/// Similar to [`background_norm_gray_array`] but uses morphological closing.
///
/// # Arguments
///
/// * `pix` - 8bpp grayscale image
/// * `mask` - Reserved for future use (must be `None`)
/// * `reduction` - Downscaling factor (2..=16)
/// * `size` - Structuring element size (odd)
/// * `bgval` - Target background value
pub fn background_norm_gray_array_morph(
    pix: &Pix,
    mask: Option<&Pix>,
    reduction: u32,
    size: u32,
    bgval: u32,
) -> FilterResult<Pix> {
    let bg_map = get_background_gray_map_morph(pix, mask, reduction, size)?;
    get_inv_background_map_inner(&bg_map, bgval, 0, 0)
}

/// Extract the inverted RGB background map arrays using morphological closing.
///
/// C版: `pixBackgroundNormRGBArraysMorph()` in `adaptmap.c`
///
/// Similar to [`background_norm_rgb_arrays`] but uses morphological closing.
///
/// # Arguments
///
/// * `pix` - 32bpp RGB image
/// * `mask` - Reserved for future use (must be `None`)
/// * `reduction` - Downscaling factor (2..=16)
/// * `size` - Structuring element size (odd)
/// * `bgval` - Target background value
pub fn background_norm_rgb_arrays_morph(
    pix: &Pix,
    mask: Option<&Pix>,
    reduction: u32,
    size: u32,
    bgval: u32,
) -> FilterResult<(Pix, Pix, Pix)> {
    let (map_r, map_g, map_b) = get_background_rgb_map_morph(pix, mask, reduction, size)?;
    let inv_r = get_inv_background_map_inner(&map_r, bgval, 0, 0)?;
    let inv_g = get_inv_background_map_inner(&map_g, bgval, 0, 0)?;
    let inv_b = get_inv_background_map_inner(&map_b, bgval, 0, 0)?;
    Ok((inv_r, inv_g, inv_b))
}

// ============================================================================
// Variable gray map and global normalization
// ============================================================================

/// Apply a variable gray map to an 8bpp image.
///
/// C版: `pixApplyVariableGrayMap()` in `adaptmap.c`
///
/// Maps each pixel linearly so that the threshold represented by `pixg`
/// becomes constant at `target`. For a pixel value `s` and map value `g`,
/// the output is `s * target / (g + 0.5)`, clamped to [0, 255].
///
/// # Arguments
///
/// * `pix` - 8bpp grayscale source image
/// * `pixg` - 8bpp variable gray map (same dimensions as `pix`)
/// * `target` - Target threshold value (typically 128)
pub fn apply_variable_gray_map(pix: &Pix, pixg: &Pix, target: u32) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8bpp",
            actual: pix.depth().bits(),
        });
    }
    if pixg.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8bpp",
            actual: pixg.depth().bits(),
        });
    }
    let w = pix.width();
    let h = pix.height();
    if pixg.width() != w || pixg.height() != h {
        return Err(FilterError::InvalidParameters(
            "pix and pixg must have the same dimensions".into(),
        ));
    }

    let target_f = target as f32;

    // For large images, use a 64K LUT for speed (index = (src << 8) | map)
    let use_lut = (w as u64) * (h as u64) > 100_000;
    let lut = if use_lut {
        let mut table = vec![0u8; 0x10000];
        for s in 0..256u32 {
            for g in 0..256u32 {
                let fval = (s as f32) * target_f / (g as f32 + 0.5);
                table[((s << 8) | g) as usize] = (fval + 0.5).min(255.0) as u8;
            }
        }
        Some(table)
    } else {
        None
    };

    let out = Pix::new(w, h, PixelDepth::Bit8)?;
    let mut out_mut = out.try_into_mut().unwrap();

    for y in 0..h {
        for x in 0..w {
            let vals = pix.get_pixel_unchecked(x, y);
            let valg = pixg.get_pixel_unchecked(x, y);
            let vald = if let Some(ref lut) = lut {
                lut[((vals << 8) | valg) as usize]
            } else {
                let fval = (vals as f32) * target_f / (valg as f32 + 0.5);
                (fval + 0.5).min(255.0) as u8
            };
            out_mut.set_pixel_unchecked(x, y, vald as u32);
        }
    }

    Ok(out_mut.into())
}

/// Global RGB normalization using per-channel TRC mapping.
///
/// C版: `pixGlobalNormRGB()` in `adaptmap.c`
///
/// Linearly maps the input color values `(rval, gval, bval)` to
/// `(mapval, mapval, mapval)`, correcting for unbalanced color channels.
/// Typically used to map an estimated white point to white (mapval=255).
///
/// # Arguments
///
/// * `pix` - 32bpp RGB image
/// * `rval` - Red channel value to map to `mapval`
/// * `gval` - Green channel value to map to `mapval`
/// * `bval` - Blue channel value to map to `mapval`
/// * `mapval` - Target output value (use 255 for white mapping)
pub fn global_norm_rgb(
    pix: &Pix,
    rval: u32,
    gval: u32,
    bval: u32,
    mapval: u32,
) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32bpp",
            actual: pix.depth().bits(),
        });
    }
    let mapval = if mapval == 0 { 255 } else { mapval };

    // Build per-channel TRC LUTs using gamma=1.0 (linear mapping)
    let r_max = (255 * rval / mapval).max(1);
    let g_max = (255 * gval / mapval).max(1);
    let b_max = (255 * bval / mapval).max(1);

    let r_lut = crate::filter::gamma_trc(1.0, 0, r_max as i32)?;
    let g_lut = crate::filter::gamma_trc(1.0, 0, g_max as i32)?;
    let b_lut = crate::filter::gamma_trc(1.0, 0, b_max as i32)?;

    let w = pix.width();
    let h = pix.height();
    let out = Pix::new(w, h, PixelDepth::Bit32)?;
    let mut out_mut = out.try_into_mut().unwrap();
    out_mut.set_spp(pix.spp());

    for y in 0..h {
        for x in 0..w {
            let pixel = pix.get_pixel_unchecked(x, y);
            let (r, g, b, _) = pixel::extract_rgba(pixel);
            let nr = r_lut[r as usize];
            let ng = g_lut[g as usize];
            let nb = b_lut[b as usize];
            out_mut.set_pixel_unchecked(x, y, pixel::compose_rgb(nr, ng, nb));
        }
    }

    Ok(out_mut.into())
}

/// Convert any-depth image to 8bpp using min-max rendering.
///
/// C版: `pixConvertTo8MinMax()` in `adaptmap.c`
///
/// For 32bpp RGB, uses min-of-RGB to strongly render color into black,
/// which is useful for document binarization. For other depths, delegates
/// to standard conversion.
pub fn convert_to_8_min_max(pix: &Pix) -> FilterResult<Pix> {
    use crate::core::pix::MinMaxType;

    match pix.depth() {
        PixelDepth::Bit32 => Ok(pix.convert_rgb_to_gray_min_max(MinMaxType::Min)?),
        _ => Ok(pix.convert_to_8()?),
    }
}

// ============================================================================
// Phase 4: Block bilateral + 追加
// ============================================================================

/// Global normalization of RGB image without saturation.
///
/// Computes the rank value of each channel at the given `rank` percentile,
/// determines the maximum scaling fraction across channels, and applies
/// `global_norm_rgb` with a `mapval` chosen to avoid saturation in all channels.
///
/// C版: `pixGlobalNormNoSatRGB()` in `adaptmap.c`
///
/// # Arguments
/// * `pix` - 32bpp RGB image
/// * `rval` - Reference red value that maps to white
/// * `gval` - Reference green value that maps to white
/// * `bval` - Reference blue value that maps to white
/// * `factor` - Subsampling factor (>= 1)
/// * `rank` - Percentile in [0.0, 1.0]; use a value close to 1.0
pub fn global_norm_no_sat_rgb(
    pix: &Pix,
    rval: u32,
    gval: u32,
    bval: u32,
    factor: u32,
    rank: f32,
) -> FilterResult<Pix> {
    if pix.depth() != PixelDepth::Bit32 {
        return Err(FilterError::UnsupportedDepth {
            expected: "32bpp",
            actual: pix.depth().bits(),
        });
    }
    if factor < 1 {
        return Err(FilterError::InvalidParameters("factor must be >= 1".into()));
    }
    if !(0.0..=1.0).contains(&rank) {
        return Err(FilterError::InvalidParameters(
            "rank must be in [0.0, 1.0]".into(),
        ));
    }
    if rval == 0 || gval == 0 || bval == 0 {
        return Err(FilterError::InvalidParameters(
            "rval, gval, bval must be > 0".into(),
        ));
    }

    let (rankrval, rankgval, rankbval) = pix
        .rank_value_masked_rgb(None, 0, 0, factor, rank)
        .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;

    let rfract = rankrval / rval as f32;
    let gfract = rankgval / gval as f32;
    let bfract = rankbval / bval as f32;
    let maxfract = rfract.max(gfract).max(bfract);

    if maxfract <= 0.0 {
        return Ok(pix.deep_clone());
    }

    let mapval = (255.0 / maxfract) as u32;
    global_norm_rgb(pix, rval, gval, bval, mapval)
}

/// Edge filter type for adaptive threshold spread normalization.
///
/// C版: `L_SOBEL_EDGE` / `L_TWO_SIDED_EDGE` in `adaptmap.c`
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EdgeFilterType {
    /// Sobel vertical edge filter (C: `L_SOBEL_EDGE`)
    Sobel,
}

/// Options for flexible background normalization.
///
/// C版: `pixBackgroundNormFlex()` parameters in `adaptmap.c`
#[derive(Debug, Clone)]
pub struct FlexNormOptions {
    /// Tile width; must be in [3, 10]
    pub tile_width: u32,
    /// Tile height; must be in [3, 10]
    pub tile_height: u32,
    /// Half-width of smoothing convolution in X; must be in [1, 3]
    pub smooth_x: u32,
    /// Half-width of smoothing convolution in Y; must be in [1, 3]
    pub smooth_y: u32,
    /// Basin-filling height delta; use 0 to skip (values > 0 not yet supported)
    pub delta: u32,
}

impl Default for FlexNormOptions {
    fn default() -> Self {
        Self {
            tile_width: 5,
            tile_height: 5,
            smooth_x: 2,
            smooth_y: 2,
            delta: 0,
        }
    }
}

/// Adaptive threshold spread normalization.
///
/// Computes a local threshold map using edge pixel values spread across the
/// image, then normalizes `pix` so that local thresholds align with a target.
///
/// # Parameters
///
/// - `pix`: 8 bpp grayscale source image; no colormap
/// - `filter_type`: edge detection method; currently only [`EdgeFilterType::Sobel`]
/// - `edge_thresh`: threshold on edge magnitude to select edge seed pixels
/// - `smooth_x`, `smooth_y`: half-width of box-blur applied to the spread map
/// - `thresh_norm`: gamma value applied to the spread map before normalization
///   (1.0 = linear; < 1.0 darkens mid-tones; > 1.0 brightens mid-tones)
///
/// Returns the background-normalized 8 bpp image.
///
/// C版: `pixThresholdSpreadNorm()` in `adaptmap.c`
pub fn threshold_spread_norm(
    pix: &Pix,
    _filter_type: EdgeFilterType,
    edge_thresh: u8,
    smooth_x: u32,
    smooth_y: u32,
    thresh_norm: f32,
) -> FilterResult<Pix> {
    use crate::region::{conncomp::ConnectivityType, seedfill::seedspread};

    use crate::filter::{
        block_conv::blockconv,
        edge::{EdgeOrientation, sobel_edge},
        enhance::gamma_trc_pix,
    };

    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }

    let w = pix.width();
    let h = pix.height();
    let thresh = edge_thresh as u32;

    // 1. Sobel vertical edge filter
    let edge_pix = sobel_edge(pix, EdgeOrientation::Vertical)?;

    // 2. Build seed image: pix values where edge is below threshold, else 0.
    //    This selects pixels near the fg/bg boundary as threshold seeds.
    let seed = Pix::new(w, h, PixelDepth::Bit8)?;
    let mut seed_mut = seed.try_into_mut().unwrap();
    for y in 0..h {
        for x in 0..w {
            let edge_val = edge_pix.get_pixel_unchecked(x, y);
            if edge_val <= thresh {
                seed_mut.set_pixel_unchecked(x, y, pix.get_pixel_unchecked(x, y));
            }
        }
    }
    let seed: Pix = seed_mut.into();

    // 3. Spread seed values to fill non-seed regions
    let spread = seedspread(&seed, ConnectivityType::FourWay)
        .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;

    // 4. Smooth the spread threshold map
    let smoothed = blockconv(&spread, smooth_x, smooth_y)?;

    // 5. Optional gamma correction on the threshold map
    let thresh_map = if (thresh_norm - 1.0).abs() < 1e-6 {
        smoothed
    } else {
        gamma_trc_pix(&smoothed, thresh_norm, 0, 255)?
    };

    // 6. Normalize pix so that local threshold aligns to 128
    apply_variable_gray_map(pix, &thresh_map, 128)
}

/// Flexible adaptive background normalization.
///
/// Generates a background estimate using smoothed subsampling, then maps the
/// image so the background is normalized to 200.  Basin-filling (delta > 0)
/// is not yet supported.
///
/// # Parameters
///
/// - `pix`: 8 bpp grayscale source image; no colormap
/// - `options`: tile size, smoothing, and delta (delta=0 skips basin filling)
///
/// C版: `pixBackgroundNormFlex()` in `adaptmap.c`
pub fn background_norm_flex(pix: &Pix, options: &FlexNormOptions) -> FilterResult<Pix> {
    use crate::transform::scale::scale_smooth;

    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    let sx = options.tile_width;
    let sy = options.tile_height;
    let smooth_x = options.smooth_x;
    let smooth_y = options.smooth_y;

    if sx < 3 || sy < 3 {
        return Err(FilterError::InvalidParameters(
            "tile_width and tile_height must be >= 3".into(),
        ));
    }
    if sx > 10 || sy > 10 {
        return Err(FilterError::InvalidParameters(
            "tile_width and tile_height must be <= 10".into(),
        ));
    }
    if smooth_x < 1 || smooth_y < 1 {
        return Err(FilterError::InvalidParameters(
            "smooth_x and smooth_y must be >= 1".into(),
        ));
    }
    if smooth_x > 3 || smooth_y > 3 {
        return Err(FilterError::InvalidParameters(
            "smooth_x and smooth_y must be <= 3".into(),
        ));
    }
    if options.delta > 0 {
        return Err(FilterError::InvalidParameters(
            "delta > 0 (basin filling) is not yet supported".into(),
        ));
    }

    // Scale down to tile-level resolution to estimate the background
    let scale_x = 1.0 / sx as f32;
    let scale_y = 1.0 / sy as f32;
    let scaled = scale_smooth(pix, scale_x, scale_y)
        .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;

    // Extend by 1 pixel on right/bottom via replication (matches C pixExtendByReplication)
    let extended = extend_by_replication(&scaled, 1, 1)?;

    // Compute the inverse background map (maps bg pixels to 200)
    let inv_map = get_inv_background_map(&extended, 200, smooth_x, smooth_y)?;

    // Apply the inverse map to the source image
    apply_inv_background_gray_map(pix, &inv_map, sx, sy)
}

/// Smooth connected foreground regions in the mask.
///
/// For each 8-connected region in `mask`, sets the corresponding pixels in
/// `pix` to the average value of those pixels.  When `mask` is `None`, the
/// image is returned unchanged.
///
/// # Parameters
///
/// - `pix`: 8 bpp grayscale; no colormap
/// - `mask`: optional 1 bpp mask defining regions to smooth
/// - `factor`: subsampling factor for computing the average (>= 1)
///
/// C版: `pixSmoothConnectedRegions()` in `adaptmap.c`
pub fn smooth_connected_regions(pix: &Pix, mask: Option<&Pix>, factor: u32) -> FilterResult<Pix> {
    use crate::core::PixelStatType;
    use crate::region::conncomp::{ConnectivityType, conncomp_pixa};

    if pix.depth() != PixelDepth::Bit8 {
        return Err(FilterError::UnsupportedDepth {
            expected: "8 bpp",
            actual: pix.depth().bits(),
        });
    }
    if factor == 0 {
        return Err(FilterError::InvalidParameters("factor must be >= 1".into()));
    }

    let mask = match mask {
        None => return Ok(pix.deep_clone()),
        Some(m) => m,
    };

    if mask.depth() != PixelDepth::Bit1 {
        return Err(FilterError::InvalidParameters("mask must be 1 bpp".into()));
    }

    let (boxa, pixa) = conncomp_pixa(mask, ConnectivityType::EightWay)
        .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;

    let n = boxa.len();
    if n == 0 {
        return Ok(pix.deep_clone());
    }

    let result = pix.deep_clone();
    let mut result_mut = result.try_into_mut().unwrap_or_else(|p| p.to_mut());

    for i in 0..n {
        let comp_mask = match pixa.get(i) {
            Some(m) => m,
            None => continue,
        };
        let b = match boxa.get(i) {
            Some(b) => b,
            None => continue,
        };

        let avg = pix
            .average_masked(Some(comp_mask), b.x, b.y, factor, PixelStatType::MeanAbsVal)
            .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;
        let avg_val = avg.round() as u32;

        result_mut
            .paint_through_mask(comp_mask, b.x, b.y, avg_val)
            .map_err(|e| FilterError::InvalidParameters(e.to_string()))?;
    }

    Ok(result_mut.into())
}

/// Binarize using background normalization with min-max color rendering.
///
/// Convenience pipeline that:
/// 1. Converts `pix` to 8 bpp grayscale using min-of-RGB (strongly renders color to black).
/// 2. Normalizes the background to 200.
/// 3. Enhances contrast according to `contrast` (1 = minimal; 10 = maximum).
/// 4. Thresholds at 180 to produce a 1 bpp binary image.
///
/// # Parameters
///
/// - `pix`: any depth, with or without colormap
/// - `contrast`: 1–10 (1 reduces contrast slightly; 10 maximizes darkening)
///
/// C版: `pixBackgroundNormTo1MinMax()` in `adaptmap.c`
pub fn background_norm_to_1_min_max(pix: &Pix, contrast: u32) -> FilterResult<Pix> {
    use crate::filter::enhance::gamma_trc_pix;

    if !(1..=10).contains(&contrast) {
        return Err(FilterError::InvalidParameters(
            "contrast must be between 1 and 10 inclusive".into(),
        ));
    }

    // Step 1: convert to 8bpp grayscale using min-of-RGB
    let gray = convert_to_8_min_max(pix)?;

    // Step 2: normalize background to ~200
    let normalized = background_norm_simple(&gray)?;

    // Step 3: selective contrast enhancement (gamma curve based on contrast level)
    let (gamma, minval, maxval) = match contrast {
        1 => (2.0f32, 50i32, 200i32),
        2 => (1.8, 60, 200),
        3 => (1.6, 70, 200),
        4 => (1.4, 80, 200),
        5 => (1.2, 90, 200),
        6 => (1.0, 100, 200),
        7 => (0.85, 110, 200),
        8 => (0.7, 120, 200),
        9 => (0.6, 130, 200),
        _ => (0.5, 140, 200), // contrast == 10
    };
    let contrasted = gamma_trc_pix(&normalized, gamma, minval, maxval)?;

    // Step 4: threshold at 180 → 1 bpp binary image
    threshold_8bpp_to_1bpp(&contrasted, 180)
}

/// Threshold an 8 bpp image to 1 bpp: output is 1 (fg) where pixel < thresh.
fn threshold_8bpp_to_1bpp(pix: &Pix, thresh: u32) -> FilterResult<Pix> {
    let w = pix.width();
    let h = pix.height();
    let out = Pix::new(w, h, PixelDepth::Bit1)?;
    let mut out_mut = out.try_into_mut().unwrap();
    for y in 0..h {
        for x in 0..w {
            let val = pix.get_pixel_unchecked(x, y);
            out_mut.set_pixel_unchecked(x, y, if val < thresh { 1 } else { 0 });
        }
    }
    Ok(out_mut.into())
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    fn create_test_gray_image() -> Pix {
        // Sized so that with the default 10x15 tile the resulting map is at
        // least 5x5 — `pixGetInvBackgroundMap` requires w/h >= 5.
        let (w, h) = (50u32, 75u32);
        let pix = Pix::new(w, h, PixelDepth::Bit8).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        // Create an image with uneven lighting (gradient + content)
        for y in 0..h {
            for x in 0..w {
                // Background gradient (darker on left, brighter on right)
                let bg = 100 + x * 2;
                // Add some "text" (dark) in the center
                let val = if (15..35).contains(&x) && y > 15 && y < (h - 15) {
                    bg / 2
                } else {
                    bg
                };
                pix_mut.set_pixel_unchecked(x, y, val.min(255));
            }
        }

        pix_mut.into()
    }

    fn create_test_color_image() -> Pix {
        // Sized so the tile-resolution map is >= 5x5 (see comment on
        // create_test_gray_image).
        let (w, h) = (50u32, 75u32);
        let pix = Pix::new(w, h, PixelDepth::Bit32).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        for y in 0..h {
            for x in 0..w {
                let r = (100 + x * 2).min(255) as u8;
                let g = (150 + y).min(255) as u8;
                let b = 180u8;
                let pixel = pixel::compose_rgb(r, g, b);
                pix_mut.set_pixel_unchecked(x, y, pixel);
            }
        }

        pix_mut.into()
    }

    fn create_low_contrast_image() -> Pix {
        let pix = Pix::new(40, 40, PixelDepth::Bit8).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        // Uniform low contrast image
        for y in 0..40 {
            for x in 0..40 {
                // Values between 100 and 120
                let val = 100 + ((x + y) % 20);
                pix_mut.set_pixel_unchecked(x, y, val);
            }
        }

        pix_mut.into()
    }

    #[test]
    fn test_background_norm_simple_gray() {
        let pix = create_test_gray_image();
        let result = background_norm_simple(&pix).unwrap();

        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit8);
    }

    #[test]
    fn test_background_norm_simple_color() {
        let pix = create_test_color_image();
        let result = background_norm_simple(&pix).unwrap();

        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit32);
    }

    #[test]
    fn test_background_norm_custom_options() {
        let pix = create_test_gray_image();
        let options = BackgroundNormOptions {
            tile_width: 8,
            tile_height: 8,
            fg_threshold: 50,
            min_count: 20,
            bg_val: 180,
            smooth_x: 1,
            smooth_y: 1,
        };
        let result = background_norm(&pix, &options).unwrap();

        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
    }

    #[test]
    fn test_background_norm_invalid_tile_size() {
        let pix = create_test_gray_image();
        let options = BackgroundNormOptions {
            tile_width: 2, // Too small
            ..Default::default()
        };
        assert!(background_norm(&pix, &options).is_err());
    }

    #[test]
    fn test_background_norm_invalid_bg_val() {
        let pix = create_test_gray_image();
        let options = BackgroundNormOptions {
            bg_val: 50, // Too small
            ..Default::default()
        };
        assert!(background_norm(&pix, &options).is_err());
    }

    #[test]
    fn test_contrast_norm_simple() {
        let pix = create_test_gray_image();
        let result = contrast_norm_simple(&pix).unwrap();

        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit8);
    }

    #[test]
    fn test_contrast_norm_custom_options() {
        let pix = create_test_gray_image();
        let options = ContrastNormOptions {
            tile_width: 10,
            tile_height: 10,
            min_diff: 30,
            smooth_x: 1,
            smooth_y: 1,
        };
        let result = contrast_norm(&pix, &options).unwrap();

        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
    }

    #[test]
    fn test_contrast_norm_invalid_tile_size() {
        let pix = create_test_gray_image();
        let options = ContrastNormOptions {
            tile_width: 3, // Too small
            ..Default::default()
        };
        assert!(contrast_norm(&pix, &options).is_err());
    }

    #[test]
    fn test_contrast_norm_invalid_smooth() {
        let pix = create_test_gray_image();
        let options = ContrastNormOptions {
            smooth_x: 10, // Too large
            ..Default::default()
        };
        assert!(contrast_norm(&pix, &options).is_err());
    }

    #[test]
    fn test_contrast_norm_color_not_supported() {
        let pix = create_test_color_image();
        let result = contrast_norm_simple(&pix);
        assert!(result.is_err());
    }

    #[test]
    fn test_contrast_norm_low_contrast_image() {
        let pix = create_low_contrast_image();
        // C-aligned semantics: when every tile falls below `min_diff`, the
        // intermediate map has no valid columns and `fill_map_holes`
        // surfaces that as InvalidParameters, matching C's
        // `pixContrastNorm` warning + error path.
        let result = contrast_norm_simple(&pix);
        assert!(
            result.is_err(),
            "expected Err on uniform low-contrast input, got {:?}",
            result
        );
    }

    #[test]
    fn test_fill_map_holes() {
        let pix = Pix::new(5, 5, PixelDepth::Bit8).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        // Set some values, leave others as holes (0)
        pix_mut.set_pixel_unchecked(0, 0, 100);
        pix_mut.set_pixel_unchecked(4, 4, 200);

        let pix = pix_mut.into();

        let filled = fill_map_holes_inner(&pix, 5, 5).unwrap();

        // Check that holes are filled
        for y in 0..5 {
            for x in 0..5 {
                let val = filled.get_pixel_unchecked(x, y);
                assert!(val > 0, "Hole at ({}, {}) not filled", x, y);
            }
        }
    }

    // -----------------------------------------------------------------------
    // Phase 3: Adaptmap拡張
    // -----------------------------------------------------------------------

    #[test]
    fn test_background_norm_to_1_min_max_basic() {
        let pix = create_test_gray_image(); // 50×50 8bpp
        let result = background_norm_to_1_min_max(&pix, 1).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit1);
    }

    #[test]
    fn test_background_norm_to_1_min_max_contrast_range() {
        let pix = create_test_gray_image();
        for contrast in 1..=10 {
            let result = background_norm_to_1_min_max(&pix, contrast).unwrap();
            assert_eq!(result.depth(), PixelDepth::Bit1);
        }
    }

    #[test]
    fn test_background_norm_to_1_min_max_invalid_contrast() {
        let pix = create_test_gray_image();
        assert!(background_norm_to_1_min_max(&pix, 0).is_err());
        assert!(background_norm_to_1_min_max(&pix, 11).is_err());
    }

    #[test]
    fn test_background_norm_flex_basic() {
        let pix = create_test_gray_image(); // 50×50 8bpp
        let opts = FlexNormOptions {
            tile_width: 5,
            tile_height: 5,
            smooth_x: 1,
            smooth_y: 1,
            delta: 0,
        };
        let result = background_norm_flex(&pix, &opts).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit8);
    }

    #[test]
    fn test_background_norm_flex_invalid_tile_size() {
        let pix = create_test_gray_image();
        // tile_width < 3 → error
        let opts = FlexNormOptions {
            tile_width: 2,
            tile_height: 5,
            smooth_x: 1,
            smooth_y: 1,
            delta: 0,
        };
        assert!(background_norm_flex(&pix, &opts).is_err());
    }

    #[test]
    fn test_threshold_spread_norm_basic() {
        let pix = create_test_gray_image(); // 50×50 8bpp
        let result = threshold_spread_norm(&pix, EdgeFilterType::Sobel, 18, 4, 4, 1.0).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit8);
    }

    #[test]
    fn test_smooth_connected_regions_no_mask() {
        let pix = create_test_gray_image(); // 50×50 8bpp
        // When mask is None, output equals input
        let result = smooth_connected_regions(&pix, None, 1).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit8);
    }

    #[test]
    fn test_smooth_connected_regions_with_mask() {
        let pix = create_test_gray_image(); // 50×50 8bpp
        // Create a simple 1bpp mask with a small fg region
        let mask = Pix::new(50, 50, PixelDepth::Bit1).unwrap();
        let mut mask_mut = mask.try_into_mut().unwrap();
        for y in 10..20 {
            for x in 10..20 {
                mask_mut.set_pixel_unchecked(x, y, 1);
            }
        }
        let mask = mask_mut.into();
        let result = smooth_connected_regions(&pix, Some(&mask), 1).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        // Pixels in the masked region should all have the same value (averaged)
        let val_ref = result.get_pixel_unchecked(10, 10);
        for y in 10..20 {
            for x in 10..20 {
                assert_eq!(result.get_pixel_unchecked(x, y), val_ref);
            }
        }
    }

    // -------------------------------------------------------------------------
    // Phase 4: global_norm_no_sat_rgb tests
    // -------------------------------------------------------------------------

    fn create_test_color_image_for_norm() -> Pix {
        let pix = Pix::new(20, 20, PixelDepth::Bit32).unwrap();
        let mut pm = pix.try_into_mut().unwrap();
        for y in 0..20u32 {
            for x in 0..20u32 {
                // Slight color imbalance: R dominant
                let r: u8 = 180;
                let g: u8 = 120;
                let b: u8 = 90;
                pm.set_pixel_unchecked(x, y, crate::core::pixel::compose_rgb(r, g, b));
            }
        }
        pm.into()
    }

    #[test]
    fn test_global_norm_no_sat_rgb_basic() {
        let pix = create_test_color_image_for_norm();
        let result = global_norm_no_sat_rgb(&pix, 180, 120, 90, 1, 1.0).unwrap();
        assert_eq!(result.width(), pix.width());
        assert_eq!(result.height(), pix.height());
        assert_eq!(result.depth(), PixelDepth::Bit32);
        // After normalization with the exact color as reference, all channels should be
        // at least as bright as before, and at least one should be strictly brighter
        let (r, g, b) = crate::core::pixel::extract_rgb(result.get_pixel_unchecked(10, 10));
        assert!(r >= 180 && g >= 120 && b >= 90 && (r > 180 || g > 120 || b > 90));
    }

    #[test]
    fn test_global_norm_no_sat_rgb_invalid_params() {
        let pix = create_test_color_image_for_norm();
        // factor 0 is invalid
        assert!(global_norm_no_sat_rgb(&pix, 180, 120, 90, 0, 0.5).is_err());
        // rank out of range
        assert!(global_norm_no_sat_rgb(&pix, 180, 120, 90, 1, 1.5).is_err());
        // zero channel value
        assert!(global_norm_no_sat_rgb(&pix, 0, 120, 90, 1, 0.5).is_err());
        // wrong depth
        let gray = Pix::new(10, 10, PixelDepth::Bit8).unwrap();
        assert!(global_norm_no_sat_rgb(&gray, 100, 100, 100, 1, 0.5).is_err());
    }
}