wifi-densepose/examples/scipix/docs/PREPROCESSING_API.md

# Preprocessing Module API Reference

## Quick Start

```rust
use ruvector_scipix::preprocess::{preprocess, PreprocessOptions};
use image::open;

// Basic preprocessing with defaults
let img = open("document.jpg")?;
let options = PreprocessOptions::default();
let processed = preprocess(&img, &options)?;
```

## Core Types

### PreprocessOptions

Complete configuration struct:

```rust
pub struct PreprocessOptions {
    pub auto_rotate: bool,              // Enable rotation detection
    pub auto_deskew: bool,              // Enable skew correction
    pub enhance_contrast: bool,         // Enable CLAHE
    pub denoise: bool,                  // Enable Gaussian blur
    pub threshold: Option<u8>,          // Manual threshold (None = auto Otsu)
    pub adaptive_threshold: bool,       // Use adaptive thresholding
    pub adaptive_window_size: u32,      // Window size for adaptive (odd number)
    pub target_width: Option<u32>,      // Resize width
    pub target_height: Option<u32>,     // Resize height
    pub detect_regions: bool,           // Enable text region detection
    pub blur_sigma: f32,                // Gaussian blur sigma
    pub clahe_clip_limit: f32,          // CLAHE clip limit
    pub clahe_tile_size: u32,           // CLAHE tile size
}
```

### TextRegion

Detected text region with metadata:

```rust
pub struct TextRegion {
    pub region_type: RegionType,        // Text, Math, Table, Figure, Unknown
    pub bbox: (u32, u32, u32, u32),     // (x, y, width, height)
    pub confidence: f32,                // 0.0 to 1.0
    pub text_height: f32,               // Average text height in pixels
    pub baseline_angle: f32,            // Baseline angle in degrees
}
```

## PreprocessPipeline Builder

### Creating a Pipeline

```rust
use ruvector_scipix::preprocess::pipeline::PreprocessPipeline;

let pipeline = PreprocessPipeline::builder()
    // Rotation & Skew
    .auto_rotate(true)
    .auto_deskew(true)
    
    // Enhancement
    .enhance_contrast(true)
    .clahe_clip_limit(2.0)    // 2.0-4.0 recommended
    .clahe_tile_size(8)        // 8 or 16
    
    // Denoising
    .denoise(true)
    .blur_sigma(1.0)           // 0.5-2.0 typical
    
    // Thresholding
    .adaptive_threshold(true)
    .adaptive_window_size(15)  // Must be odd
    .threshold(None)           // None = auto Otsu
    
    // Resizing
    .target_size(Some(800), Some(600))
    
    // Progress tracking
    .progress_callback(|step, progress| {
        println!("{}... {:.0}%", step, progress * 100.0);
    })
    
    .build();
```

### Processing

```rust
// Single image
let result = pipeline.process(&image)?;

// Batch processing (parallel)
let images = vec![img1, img2, img3];
let results = pipeline.process_batch(images)?;

// With intermediates for debugging
let intermediates = pipeline.process_with_intermediates(&image)?;
for (name, img) in intermediates {
    img.save(format!("debug_{}.png", name))?;
}
```

## Module Functions

### transforms.rs

```rust
// Basic operations
pub fn to_grayscale(image: &DynamicImage) -> GrayImage;
pub fn gaussian_blur(image: &GrayImage, sigma: f32) -> Result<GrayImage>;
pub fn sharpen(image: &GrayImage, sigma: f32, amount: f32) -> Result<GrayImage>;

// Thresholding
pub fn otsu_threshold(image: &GrayImage) -> Result<u8>;
pub fn threshold(image: &GrayImage, threshold: u8) -> GrayImage;
pub fn adaptive_threshold(image: &GrayImage, window_size: u32) -> Result<GrayImage>;
```

### rotation.rs

```rust
pub fn detect_rotation(image: &GrayImage) -> Result<f32>;
pub fn rotate_image(image: &GrayImage, angle: f32) -> Result<GrayImage>;
pub fn detect_rotation_with_confidence(image: &GrayImage) -> Result<(f32, f32)>;
pub fn auto_rotate(image: &GrayImage, confidence_threshold: f32) -> Result<(GrayImage, f32, f32)>;
```

### deskew.rs

```rust
pub fn detect_skew_angle(image: &GrayImage) -> Result<f32>;
pub fn deskew_image(image: &GrayImage, angle: f32) -> Result<GrayImage>;
pub fn auto_deskew(image: &GrayImage, max_angle: f32) -> Result<(GrayImage, f32)>;
pub fn detect_skew_projection(image: &GrayImage) -> Result<f32>;
```

### enhancement.rs

```rust
pub fn clahe(image: &GrayImage, clip_limit: f32, tile_size: u32) -> Result<GrayImage>;
pub fn normalize_brightness(image: &GrayImage) -> GrayImage;
pub fn remove_shadows(image: &GrayImage) -> Result<GrayImage>;
pub fn contrast_stretch(image: &GrayImage) -> GrayImage;
```

### segmentation.rs

```rust
pub fn find_text_regions(image: &GrayImage, min_region_size: u32) -> Result<Vec<TextRegion>>;
pub fn merge_overlapping_regions(regions: Vec<(u32, u32, u32, u32)>, merge_distance: u32) -> Vec<(u32, u32, u32, u32)>;
pub fn find_text_lines(image: &GrayImage, regions: &[(u32, u32, u32, u32)]) -> Vec<Vec<(u32, u32, u32, u32)>>;
```

## Common Workflows

### Document Scanning

```rust
let pipeline = PreprocessPipeline::builder()
    .auto_rotate(true)
    .auto_deskew(true)
    .enhance_contrast(true)
    .remove_shadows(true)  // Note: not in builder, manual call
    .adaptive_threshold(true)
    .build();
```

### Low-Quality Images

```rust
let pipeline = PreprocessPipeline::builder()
    .denoise(true)
    .blur_sigma(1.5)        // Higher blur for noise
    .enhance_contrast(true)
    .clahe_clip_limit(3.0)  // Higher clip for more contrast
    .adaptive_threshold(true)
    .adaptive_window_size(21) // Larger window
    .build();
```

### Fast Processing

```rust
let pipeline = PreprocessPipeline::builder()
    .auto_rotate(false)     // Skip if not needed
    .auto_deskew(false)
    .enhance_contrast(false)
    .denoise(false)
    .threshold(Some(128))   // Fixed threshold
    .build();
```

### High Quality

```rust
let pipeline = PreprocessPipeline::builder()
    .auto_rotate(true)
    .auto_deskew(true)
    .enhance_contrast(true)
    .clahe_clip_limit(2.0)
    .clahe_tile_size(16)    // Larger tiles
    .denoise(true)
    .blur_sigma(0.8)        // Gentle blur
    .adaptive_threshold(true)
    .adaptive_window_size(11)
    .build();
```

## Error Handling

```rust
use ruvector_scipix::preprocess::PreprocessError;

match preprocess(&img, &options) {
    Ok(processed) => { /* success */ },
    Err(PreprocessError::ImageLoad(msg)) => { /* handle load error */ },
    Err(PreprocessError::InvalidParameters(msg)) => { /* handle invalid params */ },
    Err(PreprocessError::Processing(msg)) => { /* handle processing error */ },
    Err(PreprocessError::Segmentation(msg)) => { /* handle segmentation error */ },
}
```

## Performance Tips

1. **Batch Processing**: Use `process_batch()` for multiple images
2. **Disable Unused Steps**: Turn off rotation/deskew if not needed
3. **Fixed Threshold**: Use manual threshold instead of Otsu for speed
4. **Smaller Tiles**: Use 8x8 CLAHE tiles for speed, 16x16 for quality
5. **Target Size**: Resize before processing to reduce computation

## Parameter Tuning

### blur_sigma
- **0.5-1.0**: Minimal noise reduction
- **1.0-1.5**: Moderate (recommended)
- **1.5-2.5**: Heavy denoising

### clahe_clip_limit
- **1.5-2.0**: Subtle enhancement
- **2.0-3.0**: Moderate (recommended)
- **3.0-4.0**: Strong enhancement

### clahe_tile_size
- **4**: Very local, may cause artifacts
- **8**: Good balance (recommended)
- **16**: Smoother, less local

### adaptive_window_size
- **7-11**: Small features, faster
- **13-17**: Medium (recommended)
- **19-25**: Large features, slower

## Examples

See `/home/user/ruvector/examples/scipix/examples/` for complete working examples.