leptonica 0.4.0

//! Pixel labeling functions
//!
//! This module provides high-level functions for labeling and analyzing
//! connected components in images.

use crate::core::{Box, Pix, PixelDepth};
use crate::region::conncomp::{ConnectivityType, label_connected_components};
use crate::region::error::{RegionError, RegionResult};

/// Label connected components in an image
///
/// This is a convenience wrapper around `label_connected_components` that
/// supports multiple image depths by first converting to binary.
///
/// # Arguments
///
/// * `pix` - Input image (1-bit binary)
/// * `connectivity` - Connectivity type (4-way or 8-way)
///
/// # Returns
///
/// A 32-bit labeled image where each pixel contains its component label.
pub fn pix_label_connected_components(
    pix: &Pix,
    connectivity: ConnectivityType,
) -> RegionResult<Pix> {
    if pix.depth() != PixelDepth::Bit1 {
        return Err(RegionError::UnsupportedDepth {
            expected: "1-bit",
            actual: pix.depth().bits(),
        });
    }

    label_connected_components(pix, connectivity)
}

/// Count the number of connected components
///
/// # Arguments
///
/// * `pix` - Input binary image (1-bit)
/// * `connectivity` - Connectivity type
///
/// # Returns
///
/// The number of foreground connected components.
pub fn pix_count_components(pix: &Pix, connectivity: ConnectivityType) -> RegionResult<u32> {
    let labeled = pix_label_connected_components(pix, connectivity)?;

    // Find the maximum label value
    let width = labeled.width();
    let height = labeled.height();
    let mut max_label = 0u32;

    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y) {
                max_label = max_label.max(label);
            }
        }
    }

    Ok(max_label)
}

/// Get bounding boxes for all connected components
///
/// # Arguments
///
/// * `pix` - Input binary image (1-bit)
/// * `connectivity` - Connectivity type
///
/// # Returns
///
/// A vector of bounding boxes, one for each component.
/// The index in the vector corresponds to (label - 1).
pub fn pix_get_component_bounds(
    pix: &Pix,
    connectivity: ConnectivityType,
) -> RegionResult<Vec<Box>> {
    let labeled = pix_label_connected_components(pix, connectivity)?;
    get_component_bounds_from_labels(&labeled)
}

/// Get bounding boxes from a labeled image
///
/// # Arguments
///
/// * `labeled` - Labeled image (32-bit)
///
/// # Returns
///
/// A vector of bounding boxes, one for each component.
pub fn get_component_bounds_from_labels(labeled: &Pix) -> RegionResult<Vec<Box>> {
    if labeled.depth() != PixelDepth::Bit32 {
        return Err(RegionError::UnsupportedDepth {
            expected: "32-bit (labeled image)",
            actual: labeled.depth().bits(),
        });
    }

    let width = labeled.width();
    let height = labeled.height();

    // Collect bounds for each label
    let mut bounds_map: std::collections::HashMap<u32, (i32, i32, i32, i32)> =
        std::collections::HashMap::new();

    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y)
                && label > 0
            {
                let entry = bounds_map
                    .entry(label)
                    .or_insert((x as i32, y as i32, x as i32, y as i32));
                entry.0 = entry.0.min(x as i32); // min_x
                entry.1 = entry.1.min(y as i32); // min_y
                entry.2 = entry.2.max(x as i32); // max_x
                entry.3 = entry.3.max(y as i32); // max_y
            }
        }
    }

    // Convert to sorted vector of Box
    let mut label_bounds: Vec<(u32, Box)> = bounds_map
        .into_iter()
        .map(|(label, (min_x, min_y, max_x, max_y))| {
            (
                label,
                Box::new_unchecked(min_x, min_y, max_x - min_x + 1, max_y - min_y + 1),
            )
        })
        .collect();

    label_bounds.sort_by_key(|(label, _)| *label);

    Ok(label_bounds.into_iter().map(|(_, b)| b).collect())
}

/// Get pixel count for each component
///
/// # Arguments
///
/// * `labeled` - Labeled image (32-bit)
///
/// # Returns
///
/// A vector of pixel counts, one for each component.
/// The index corresponds to (label - 1).
pub fn get_component_sizes(labeled: &Pix) -> RegionResult<Vec<u32>> {
    if labeled.depth() != PixelDepth::Bit32 {
        return Err(RegionError::UnsupportedDepth {
            expected: "32-bit (labeled image)",
            actual: labeled.depth().bits(),
        });
    }

    let width = labeled.width();
    let height = labeled.height();

    // Count pixels for each label
    let mut counts: std::collections::HashMap<u32, u32> = std::collections::HashMap::new();

    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y)
                && label > 0
            {
                *counts.entry(label).or_insert(0) += 1;
            }
        }
    }

    // Convert to sorted vector
    let mut label_counts: Vec<(u32, u32)> = counts.into_iter().collect();
    label_counts.sort_by_key(|(label, _)| *label);

    Ok(label_counts.into_iter().map(|(_, count)| count).collect())
}

/// Component statistics
#[derive(Debug, Clone)]
pub struct ComponentStats {
    /// Component label
    pub label: u32,
    /// Bounding box
    pub bounds: Box,
    /// Number of pixels
    pub pixel_count: u32,
    /// Centroid X coordinate
    pub centroid_x: f64,
    /// Centroid Y coordinate
    pub centroid_y: f64,
}

/// Get detailed statistics for all components
///
/// # Arguments
///
/// * `labeled` - Labeled image (32-bit)
///
/// # Returns
///
/// A vector of component statistics.
pub fn get_component_stats(labeled: &Pix) -> RegionResult<Vec<ComponentStats>> {
    if labeled.depth() != PixelDepth::Bit32 {
        return Err(RegionError::UnsupportedDepth {
            expected: "32-bit (labeled image)",
            actual: labeled.depth().bits(),
        });
    }

    let width = labeled.width();
    let height = labeled.height();

    // Accumulate statistics for each label
    #[derive(Default)]
    struct Accum {
        count: u32,
        sum_x: u64,
        sum_y: u64,
        min_x: i32,
        min_y: i32,
        max_x: i32,
        max_y: i32,
    }

    let mut stats: std::collections::HashMap<u32, Accum> = std::collections::HashMap::new();

    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y)
                && label > 0
            {
                let acc = stats.entry(label).or_insert_with(|| Accum {
                    count: 0,
                    sum_x: 0,
                    sum_y: 0,
                    min_x: x as i32,
                    min_y: y as i32,
                    max_x: x as i32,
                    max_y: y as i32,
                });

                acc.count += 1;
                acc.sum_x += x as u64;
                acc.sum_y += y as u64;
                acc.min_x = acc.min_x.min(x as i32);
                acc.min_y = acc.min_y.min(y as i32);
                acc.max_x = acc.max_x.max(x as i32);
                acc.max_y = acc.max_y.max(y as i32);
            }
        }
    }

    // Convert to ComponentStats
    let mut result: Vec<ComponentStats> = stats
        .into_iter()
        .map(|(label, acc)| {
            let centroid_x = acc.sum_x as f64 / acc.count as f64;
            let centroid_y = acc.sum_y as f64 / acc.count as f64;
            let bounds = Box::new_unchecked(
                acc.min_x,
                acc.min_y,
                acc.max_x - acc.min_x + 1,
                acc.max_y - acc.min_y + 1,
            );

            ComponentStats {
                label,
                bounds,
                pixel_count: acc.count,
                centroid_x,
                centroid_y,
            }
        })
        .collect();

    result.sort_by_key(|s| s.label);

    Ok(result)
}

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

    fn create_test_image(width: u32, height: u32, pixels: &[(u32, u32)]) -> Pix {
        let pix = Pix::new(width, height, PixelDepth::Bit1).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        for &(x, y) in pixels {
            let _ = pix_mut.set_pixel(x, y, 1);
        }

        pix_mut.into()
    }

    #[test]
    fn test_count_components() {
        let pix = create_test_image(
            10,
            10,
            &[
                (0, 0),
                (1, 0), // Component 1
                (5, 5),
                (6, 5), // Component 2
                (8, 8), // Component 3
            ],
        );

        let count = pix_count_components(&pix, ConnectivityType::FourWay).unwrap();
        assert_eq!(count, 3);
    }

    #[test]
    fn test_get_component_bounds() {
        let pix = create_test_image(10, 10, &[(0, 0), (1, 0), (2, 0), (1, 1)]);

        let bounds = pix_get_component_bounds(&pix, ConnectivityType::FourWay).unwrap();

        assert_eq!(bounds.len(), 1);
        assert_eq!(bounds[0].x, 0);
        assert_eq!(bounds[0].y, 0);
        assert_eq!(bounds[0].w, 3);
        assert_eq!(bounds[0].h, 2);
    }

    #[test]
    fn test_get_component_sizes() {
        let pix = create_test_image(
            10,
            10,
            &[
                (0, 0),
                (1, 0), // 2 pixels
                (5, 5), // 1 pixel
            ],
        );

        let labeled = pix_label_connected_components(&pix, ConnectivityType::FourWay).unwrap();
        let sizes = get_component_sizes(&labeled).unwrap();

        assert_eq!(sizes.len(), 2);
        // Sizes should be 2 and 1 (order depends on labeling)
        assert!(sizes.contains(&2));
        assert!(sizes.contains(&1));
    }

    #[test]
    fn test_get_component_stats() {
        let pix = create_test_image(10, 10, &[(0, 0), (2, 0), (1, 1)]); // L-shape

        let labeled = pix_label_connected_components(&pix, ConnectivityType::EightWay).unwrap();
        let stats = get_component_stats(&labeled).unwrap();

        assert_eq!(stats.len(), 1);
        assert_eq!(stats[0].pixel_count, 3);

        // Centroid should be at (1, 0.333...)
        assert!((stats[0].centroid_x - 1.0).abs() < 0.01);
        assert!((stats[0].centroid_y - 1.0 / 3.0).abs() < 0.01);
    }

    #[test]
    fn test_empty_image() {
        let pix = create_test_image(10, 10, &[]);

        let count = pix_count_components(&pix, ConnectivityType::FourWay).unwrap();
        assert_eq!(count, 0);

        let bounds = pix_get_component_bounds(&pix, ConnectivityType::FourWay).unwrap();
        assert!(bounds.is_empty());
    }
}

// ===== Phase 4 Label Extensions =====

/// Transformation type for connected components
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConnCompTransform {
    /// Transform to area (pixel count) of each component
    Area,
    /// Transform to label number
    Label,
}

/// Transform connected components by replacing pixel values with transformation results
///
/// Each connected component is filled with a value determined by the transformation type:
/// - Area: pixel count of the component
/// - Label: label number of the component
///
/// # Arguments
///
/// * `pix` - Input binary image (1-bit)
/// * `connectivity` - Connectivity type (4-way or 8-way)
/// * `transform_type` - Type of transformation (Area or Label)
///
/// # Returns
///
/// A 32-bit image where each pixel contains the transformed value.
pub fn conn_comp_transform(
    pix: &Pix,
    connectivity: ConnectivityType,
    transform_type: ConnCompTransform,
) -> RegionResult<Pix> {
    // Get labeled image
    let labeled = label_connected_components(pix, connectivity)?;

    // Get component sizes
    let sizes = get_component_sizes(&labeled)?;

    let width = labeled.width();
    let height = labeled.height();

    // Create output image (32-bit)
    let output = Pix::new(width, height, PixelDepth::Bit32).map_err(RegionError::Core)?;
    let mut result = output.try_into_mut().unwrap_or_else(|p| p.to_mut());

    // Transform pixel values based on type
    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y) {
                let value = if label > 0 {
                    match transform_type {
                        ConnCompTransform::Area => {
                            // Get area (pixel count) - labels are 1-indexed
                            sizes.get(label as usize - 1).copied().unwrap_or(0)
                        }
                        ConnCompTransform::Label => label,
                    }
                } else {
                    0
                };

                let _ = result.set_pixel(x, y, value);
            }
        }
    }

    Ok(result.into())
}

/// Incremental connected component labeler
///
/// Allows components to be added sequentially with automatic label assignment.
/// Union-find: find root with path halving
fn uf_find(parent: &mut [u32], mut x: u32) -> u32 {
    while parent[x as usize] != x {
        parent[x as usize] = parent[parent[x as usize] as usize];
        x = parent[x as usize];
    }
    x
}

/// Union-find: merge two sets by rank
fn uf_union(parent: &mut [u32], rank: &mut [u8], x: u32, y: u32) {
    let rx = uf_find(parent, x);
    let ry = uf_find(parent, y);
    if rx == ry {
        return;
    }
    if rank[rx as usize] < rank[ry as usize] {
        parent[rx as usize] = ry;
    } else if rank[rx as usize] > rank[ry as usize] {
        parent[ry as usize] = rx;
    } else {
        parent[ry as usize] = rx;
        rank[rx as usize] += 1;
    }
}

pub struct IncrementalLabeler {
    width: u32,
    height: u32,
    connectivity: ConnectivityType,
    labels: Vec<u32>,
    next_label: u32,
    parent: Vec<u32>,
    rank: Vec<u8>,
}

impl std::fmt::Debug for IncrementalLabeler {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("IncrementalLabeler")
            .field("width", &self.width)
            .field("height", &self.height)
            .field("connectivity", &self.connectivity)
            .field("next_label", &self.next_label)
            .finish()
    }
}

impl IncrementalLabeler {
    /// Create a new incremental labeler
    ///
    /// # Arguments
    ///
    /// * `width` - Image width
    /// * `height` - Image height
    /// * `connectivity` - Connectivity type (4-way or 8-way)
    pub fn new(width: u32, height: u32, connectivity: ConnectivityType) -> Self {
        let size = (width as usize)
            .checked_mul(height as usize)
            .expect("image dimensions too large to allocate labels");
        Self {
            width,
            height,
            connectivity,
            labels: vec![0; size],
            next_label: 1,
            parent: vec![0],
            rank: vec![0],
        }
    }

    /// Add a new component at the given position
    ///
    /// Uses BFS to find connected pixels and assigns them to the next label.
    ///
    /// # Arguments
    ///
    /// * `pix` - Source image (must be 1-bit binary)
    /// * `x` - X coordinate of seed point
    /// * `y` - Y coordinate of seed point
    pub fn add_component(&mut self, pix: &Pix, x: u32, y: u32) -> RegionResult<u32> {
        // Check bounds and validate seed position within the labeler
        if x >= self.width || y >= self.height {
            return Err(RegionError::InvalidSeed { x, y });
        }

        // Ensure the source image is 1-bit binary as documented
        if pix.depth() != PixelDepth::Bit1 {
            return Err(RegionError::UnsupportedDepth {
                expected: "1-bit",
                actual: pix.depth().bits(),
            });
        }

        // Ensure the source image dimensions match the labeler dimensions
        if pix.width() != self.width || pix.height() != self.height {
            return Err(RegionError::InvalidSeed { x, y });
        }

        // Check if seed point is already labeled
        let idx = (y * self.width + x) as usize;
        if self.labels[idx] != 0 {
            return Ok(self.labels[idx]); // Already labeled
        }

        // Check if seed point is valid foreground; treat None or 0 as invalid
        match pix.get_pixel(x, y) {
            Some(1) => {} // valid foreground seed
            _ => return Err(RegionError::InvalidSeed { x, y }),
        }

        // BFS to find all connected pixels
        let label = self.next_label;
        self.parent.push(label);
        self.rank.push(0);
        let mut queue = std::collections::VecDeque::new();
        queue.push_back((x, y));
        self.labels[idx] = label;

        const FOUR_WAY: &[(i32, i32)] = &[
            (0, -1), // up
            (0, 1),  // down
            (-1, 0), // left
            (1, 0),  // right
        ];
        const EIGHT_WAY: &[(i32, i32)] = &[
            (0, -1),  // up
            (0, 1),   // down
            (-1, 0),  // left
            (1, 0),   // right
            (-1, -1), // up-left
            (1, -1),  // up-right
            (-1, 1),  // down-left
            (1, 1),   // down-right
        ];
        let offsets: &[(i32, i32)] = match self.connectivity {
            ConnectivityType::FourWay => FOUR_WAY,
            ConnectivityType::EightWay => EIGHT_WAY,
        };

        while let Some((cx, cy)) = queue.pop_front() {
            for &(dx, dy) in offsets {
                let nx = cx as i32 + dx;
                let ny = cy as i32 + dy;

                // Check bounds
                if nx < 0 || nx >= self.width as i32 || ny < 0 || ny >= self.height as i32 {
                    continue;
                }

                let nx = nx as u32;
                let ny = ny as u32;
                let n_idx = (ny * self.width + nx) as usize;

                // Check if already labeled
                if self.labels[n_idx] != 0 {
                    continue;
                }

                // Check if foreground
                if pix.get_pixel(nx, ny) != Some(1) {
                    continue;
                }

                // Label and enqueue
                self.labels[n_idx] = label;
                queue.push_back((nx, ny));
            }
        }

        self.next_label += 1;
        Ok(label)
    }

    /// Get the resulting labeled image
    pub fn finish(mut self) -> Pix {
        // Create a 32-bit image
        let pix =
            Pix::new(self.width, self.height, PixelDepth::Bit32).expect("Failed to allocate image");
        let mut pix_mut = pix.try_into_mut().unwrap_or_else(|p| p.to_mut());

        for idx in 0..self.labels.len() {
            let label = self.labels[idx];
            let resolved = if label > 0 {
                uf_find(&mut self.parent, label)
            } else {
                0
            };
            let y = (idx as u32) / self.width;
            let x = (idx as u32) % self.width;
            let _ = pix_mut.set_pixel(x, y, resolved);
        }

        pix_mut.into()
    }
}

/// Convert a labeled image to a color image for visualization
///
/// Each unique label is deterministically mapped to a color from a fixed
/// palette based on its numeric value. This function does not analyze spatial
/// adjacency, so adjacent components may share the same color.
///
/// # Arguments
///
/// * `labeled` - Labeled image (32-bit, output from label_connected_components)
///
/// # Returns
///
/// A 32-bit RGBA image where each pixel contains a color for its label.
pub fn label_to_color(labeled: &Pix) -> RegionResult<Pix> {
    if labeled.depth() != PixelDepth::Bit32 {
        return Err(RegionError::UnsupportedDepth {
            expected: "32-bit (labeled image)",
            actual: labeled.depth().bits(),
        });
    }

    let width = labeled.width();
    let height = labeled.height();

    // Create output image (32-bit RGBA)
    let pix = Pix::new(width, height, PixelDepth::Bit32).map_err(RegionError::Core)?;
    let mut pix_mut = pix.try_into_mut().unwrap_or_else(|p| p.to_mut());

    // Pre-generate colors for all labels using a simple hash-based approach
    // This ensures deterministic color assignment
    let mut color_map: std::collections::HashMap<u32, u32> = std::collections::HashMap::new();

    // Standard palette colors for good visual separation
    let palette = vec![
        0xFF0000FF, // Red
        0x00FF00FF, // Green
        0x0000FFFF, // Blue
        0xFFFF00FF, // Yellow
        0xFF00FFFF, // Magenta
        0x00FFFFFF, // Cyan
        0xFF8000FF, // Orange
        0x8000FFFF, // Purple
        0x00FF80FF, // Spring Green
        0xFF0080FF, // Rose
        0x80FF00FF, // Chartreuse
        0x0080FFFF, // Sky Blue
    ];

    // Assign colors to labels
    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y) {
                let color = if label == 0 {
                    0x000000FF // Black, opaque background (0xRRGGBBAA)
                } else {
                    // Use existing color if assigned, otherwise generate new one
                    if let Some(&c) = color_map.get(&label) {
                        c
                    } else {
                        // Simple hash-based color assignment
                        let idx = (label as usize).wrapping_mul(2654435761) % palette.len();
                        let c = palette[idx];
                        color_map.insert(label, c);
                        c
                    }
                };

                let _ = pix_mut.set_pixel(x, y, color);
            }
        }
    }

    Ok(pix_mut.into())
}

/// Initialize incremental connected component labeling from a binary image
///
/// Creates an `IncrementalLabeler` pre-populated with all existing foreground
/// components from the input image. New pixels can then be added incrementally
/// using `pix_conn_comp_incr_add`.
///
/// Rust equivalent of C `pixConnCompIncrInit`.
///
/// # Arguments
///
/// * `pix` - Input binary image (1-bit)
/// * `connectivity` - Connectivity type (4-way or 8-way)
///
/// # Returns
///
/// A tuple of (IncrementalLabeler, number_of_components).
pub fn pix_conn_comp_incr_init(
    pix: &Pix,
    connectivity: ConnectivityType,
) -> RegionResult<(IncrementalLabeler, u32)> {
    if pix.depth() != PixelDepth::Bit1 {
        return Err(RegionError::UnsupportedDepth {
            expected: "1-bit",
            actual: pix.depth().bits(),
        });
    }

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

    // Check if image is empty
    let mut has_fg = false;
    'outer: for y in 0..height {
        for x in 0..width {
            if pix.get_pixel(x, y) == Some(1) {
                has_fg = true;
                break 'outer;
            }
        }
    }

    if !has_fg {
        return Ok((IncrementalLabeler::new(width, height, connectivity), 0));
    }

    // Label existing components
    let labeled = label_connected_components(pix, connectivity)?;

    // Find max label
    let mut max_label = 0u32;
    let mut labeler = IncrementalLabeler::new(width, height, connectivity);

    for y in 0..height {
        for x in 0..width {
            if let Some(label) = labeled.get_pixel(x, y)
                && label > 0
            {
                let idx = (y * width + x) as usize;
                labeler.labels[idx] = label;
                if label > max_label {
                    max_label = label;
                }
            }
        }
    }

    labeler.next_label = max_label + 1;
    labeler.parent = (0..=max_label).collect();
    labeler.rank = vec![0; (max_label + 1) as usize];
    Ok((labeler, max_label))
}

/// Add a single pixel to incremental connected component labeling
///
/// Adds the pixel at (x, y) and updates labels. If the pixel connects
/// existing components, they are merged.
///
/// Rust equivalent of C `pixConnCompIncrAdd`.
///
/// # Arguments
///
/// * `labeler` - The incremental labeler
/// * `ncc` - Current number of components (updated in place)
/// * `x` - X coordinate of pixel to add
/// * `y` - Y coordinate of pixel to add
///
/// # Returns
///
/// Ok(()) on success, Err if coordinates are out of bounds.
pub fn pix_conn_comp_incr_add(
    labeler: &mut IncrementalLabeler,
    ncc: &mut u32,
    x: u32,
    y: u32,
) -> RegionResult<()> {
    if x >= labeler.width || y >= labeler.height {
        return Err(RegionError::InvalidSeed { x, y });
    }

    let idx = (y * labeler.width + x) as usize;

    // Already labeled
    if labeler.labels[idx] != 0 {
        return Ok(());
    }

    // Find unique neighbor labels
    let offsets: &[(i32, i32)] = match labeler.connectivity {
        ConnectivityType::FourWay => &[(0, -1), (0, 1), (-1, 0), (1, 0)],
        ConnectivityType::EightWay => &[
            (0, -1),
            (0, 1),
            (-1, 0),
            (1, 0),
            (-1, -1),
            (1, -1),
            (-1, 1),
            (1, 1),
        ],
    };

    let mut neighbor_labels: Vec<u32> = Vec::with_capacity(8);
    for &(dx, dy) in offsets {
        let nx = x as i32 + dx;
        let ny = y as i32 + dy;
        if nx >= 0 && nx < labeler.width as i32 && ny >= 0 && ny < labeler.height as i32 {
            let n_idx = (ny as u32 * labeler.width + nx as u32) as usize;
            let val = labeler.labels[n_idx];
            if val > 0 {
                let root = uf_find(&mut labeler.parent, val);
                if !neighbor_labels.contains(&root) {
                    neighbor_labels.push(root);
                }
            }
        }
    }
    neighbor_labels.sort_unstable();

    if neighbor_labels.is_empty() {
        // New isolated component
        let label = labeler.next_label;
        labeler.labels[idx] = label;
        labeler.parent.push(label);
        labeler.rank.push(0);
        labeler.next_label += 1;
        *ncc += 1;
    } else {
        // Assign to the smallest neighbor label
        let first_label = neighbor_labels[0];
        labeler.labels[idx] = first_label;

        // Union all neighbor labels via union-find
        if neighbor_labels.len() > 1 {
            for &other_label in &neighbor_labels[1..] {
                uf_union(
                    &mut labeler.parent,
                    &mut labeler.rank,
                    first_label,
                    other_label,
                );
                *ncc -= 1;
            }
        }
    }

    Ok(())
}

/// Transform pixel locations to color encoding
///
/// Creates an RGB image where each foreground pixel is colored based on its
/// (x, y) location and the area of its connected component. The encoding is
/// approximately invariant to 4-fold orthogonal rotation and weakly depends
/// on translation/small rotation.
///
/// Rust equivalent of C `pixLocToColorTransform`.
///
/// # Arguments
///
/// * `pix` - Input binary image (1-bit)
///
/// # Returns
///
/// A 32-bit RGBA image. Background pixels are black (0x00000000).
pub fn pix_loc_to_color_transform(pix: &Pix) -> RegionResult<Pix> {
    use crate::core::pixel::compose_rgba;

    if pix.depth() != PixelDepth::Bit1 {
        return Err(RegionError::UnsupportedDepth {
            expected: "1-bit",
            actual: pix.depth().bits(),
        });
    }

    let w = pix.width();
    let h = pix.height();
    let w2 = w / 2;
    let h2 = h / 2;
    let inv_w2 = if w2 > 0 { 255.0 / w2 as f32 } else { 0.0 };
    let inv_h2 = if h2 > 0 { 255.0 / h2 as f32 } else { 0.0 };

    // Get connected component area transform (label each pixel with its component area)
    let area_pix = crate::region::conncomp::component_area_transform(&label_connected_components(
        pix,
        ConnectivityType::EightWay,
    )?)?;

    // Create output 32-bit image
    let out = Pix::new(w, h, PixelDepth::Bit32).map_err(RegionError::Core)?;
    let mut out_mut = out.try_into_mut().unwrap_or_else(|p| p.to_mut());

    for y in 0..h {
        for x in 0..w {
            if pix.get_pixel(x, y).unwrap_or(0) == 0 {
                continue;
            }

            let (rval, gval) = if w < h {
                let r = (inv_h2 * (y as f32 - h2 as f32).abs()) as u8;
                let g = (inv_w2 * (x as f32 - w2 as f32).abs()) as u8;
                (r, g)
            } else {
                let r = (inv_w2 * (x as f32 - w2 as f32).abs()) as u8;
                let g = (inv_h2 * (y as f32 - h2 as f32).abs()) as u8;
                (r, g)
            };

            // Blue channel: component area clipped to 255
            let area = area_pix.get_pixel(x, y).unwrap_or(0);
            let bval = area.min(255) as u8;

            let color = compose_rgba(rval, gval, bval, 255);
            let _ = out_mut.set_pixel(x, y, color);
        }
    }

    Ok(out_mut.into())
}

/// Get the unique sorted neighbor values for a pixel in a labeled image.
///
/// Returns the set of non-zero neighboring pixel values, sorted smallest
/// to largest. Background (0) values are excluded.
///
/// # Arguments
///
/// * `pix` - Labeled image (8, 16, or 32 bpp)
/// * `x` - X coordinate
/// * `y` - Y coordinate
/// * `connectivity` - 4-way or 8-way connectivity
///
/// # Returns
///
/// A sorted Vec of unique non-zero neighbor values.
///
/// # Reference
///
/// C Leptonica: `pixGetSortedNeighborValues()`
pub fn pix_get_sorted_neighbor_values(
    pix: &Pix,
    x: u32,
    y: u32,
    connectivity: ConnectivityType,
) -> RegionResult<Vec<u32>> {
    let depth = pix.depth().bits();
    if depth < 8 {
        return Err(RegionError::UnsupportedDepth {
            expected: "8, 16, or 32 bpp",
            actual: depth,
        });
    }

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

    let neighbors: Vec<(i32, i32)> = match connectivity {
        ConnectivityType::FourWay => vec![(-1, 0), (1, 0), (0, -1), (0, 1)],
        ConnectivityType::EightWay => vec![
            (-1, -1),
            (0, -1),
            (1, -1),
            (-1, 0),
            (1, 0),
            (-1, 1),
            (0, 1),
            (1, 1),
        ],
    };

    let mut values = std::collections::BTreeSet::new();
    for (dx, dy) in &neighbors {
        let nx = x as i32 + dx;
        let ny = y as i32 + dy;
        if nx >= 0
            && ny >= 0
            && (nx as u32) < w
            && (ny as u32) < h
            && let Some(val) = pix.get_pixel(nx as u32, ny as u32)
            && val != 0
        {
            values.insert(val);
        }
    }

    Ok(values.into_iter().collect())
}

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

    fn create_test_image_with_components(width: u32, height: u32) -> Pix {
        let pix = Pix::new(width, height, PixelDepth::Bit1).unwrap();
        let mut pix_mut = pix.try_into_mut().unwrap();

        // Component 1: 2x2 square at (1,1)
        for x in 1..3 {
            for y in 1..3 {
                let _ = pix_mut.set_pixel(x, y, 1);
            }
        }

        // Component 2: 3x1 line at (6,5)
        for x in 6..9 {
            let _ = pix_mut.set_pixel(x, 5, 1);
        }

        // Component 3: single pixel at (2,8)
        let _ = pix_mut.set_pixel(2, 8, 1);

        pix_mut.into()
    }

    #[test]
    fn test_conn_comp_area_transform() {
        let pix = create_test_image_with_components(10, 10);

        let transformed =
            conn_comp_transform(&pix, ConnectivityType::FourWay, ConnCompTransform::Area).unwrap();

        // Component 1: 4 pixels
        assert_eq!(transformed.get_pixel(1, 1), Some(4));
        assert_eq!(transformed.get_pixel(2, 2), Some(4));

        // Component 2: 3 pixels
        assert_eq!(transformed.get_pixel(6, 5), Some(3));
        assert_eq!(transformed.get_pixel(8, 5), Some(3));

        // Component 3: 1 pixel
        assert_eq!(transformed.get_pixel(2, 8), Some(1));

        // Background: 0
        assert_eq!(transformed.get_pixel(0, 0), Some(0));
    }

    #[test]
    fn test_conn_comp_label_transform() {
        let pix = create_test_image_with_components(10, 10);

        let transformed =
            conn_comp_transform(&pix, ConnectivityType::FourWay, ConnCompTransform::Label).unwrap();

        // All pixels in component 1 should have same label
        let label1 = transformed.get_pixel(1, 1).unwrap();
        assert_eq!(transformed.get_pixel(2, 2), Some(label1));

        // All pixels in component 2 should have same (different) label
        let label2 = transformed.get_pixel(6, 5).unwrap();
        assert_ne!(label2, label1);
        assert_eq!(transformed.get_pixel(8, 5), Some(label2));

        // Component 3 should have yet another label
        let label3 = transformed.get_pixel(2, 8).unwrap();
        assert_ne!(label3, label1);
        assert_ne!(label3, label2);

        // Background: 0
        assert_eq!(transformed.get_pixel(0, 0), Some(0));
    }

    #[test]
    fn test_incremental_labeler_basic() {
        let pix = create_test_image_with_components(10, 10);

        let mut labeler = IncrementalLabeler::new(10, 10, ConnectivityType::FourWay);

        // Add first component at (1,1)
        let label1 = labeler.add_component(&pix, 1, 1).unwrap();
        assert_eq!(label1, 1);

        // Add second component at (6,5)
        let label2 = labeler.add_component(&pix, 6, 5).unwrap();
        assert_eq!(label2, 2);

        // Add third component at (2,8)
        let label3 = labeler.add_component(&pix, 2, 8).unwrap();
        assert_eq!(label3, 3);

        let result = labeler.finish();

        // Verify labeling
        assert_eq!(result.get_pixel(1, 1), Some(label1));
        assert_eq!(result.get_pixel(2, 2), Some(label1));
        assert_eq!(result.get_pixel(6, 5), Some(label2));
        assert_eq!(result.get_pixel(2, 8), Some(label3));
    }

    #[test]
    fn test_incremental_vs_batch_labeling() {
        let pix = create_test_image_with_components(10, 10);

        // Incremental labeling
        let mut labeler = IncrementalLabeler::new(10, 10, ConnectivityType::FourWay);
        let _ = labeler.add_component(&pix, 1, 1);
        let _ = labeler.add_component(&pix, 6, 5);
        let _ = labeler.add_component(&pix, 2, 8);
        let incremental_result = labeler.finish();

        // Both should produce the same number of components.
        // Scan max label from the 32-bit labeled image (pix_count_components requires 1-bit input).
        let batch_count = pix_count_components(&pix, ConnectivityType::FourWay).unwrap();
        let incremental_count = get_component_sizes(&incremental_result).unwrap().len() as u32;

        assert_eq!(batch_count, incremental_count);
    }

    #[test]
    fn test_label_to_color_basic() {
        let pix = create_test_image_with_components(10, 10);
        let labeled = pix_label_connected_components(&pix, ConnectivityType::FourWay).unwrap();

        let colored = label_to_color(&labeled).unwrap();

        // Check depth is 32-bit
        assert_eq!(colored.depth(), PixelDepth::Bit32);

        // Check that colored image has correct dimensions
        assert_eq!(colored.width(), labeled.width());
        assert_eq!(colored.height(), labeled.height());

        // Background should be opaque black (0xRRGGBBAA format)
        let bg_color = colored.get_pixel(0, 0).unwrap();
        assert_eq!(bg_color, 0x000000FF); // Opaque black in 0xRRGGBBAA
    }

    #[test]
    fn test_label_to_color_adjacent_different() {
        let pix = create_test_image_with_components(10, 10);
        let labeled = pix_label_connected_components(&pix, ConnectivityType::FourWay).unwrap();

        let colored = label_to_color(&labeled).unwrap();

        // Component 1 at (1,1) and (1,2) should have same color
        let color1 = colored.get_pixel(1, 1).unwrap();
        assert_eq!(colored.get_pixel(1, 2), Some(color1));

        // Adjacent different components should ideally have different colors
        // (implementation may not guarantee this for all adjacencies, but should try)
        let _color2 = colored.get_pixel(6, 5).unwrap();
        let _color3 = colored.get_pixel(2, 8).unwrap();
        // Note: exact color difference check would depend on implementation
    }
}