# Image Preprocessing Guide

**Last Updated:** 2026-01-20

## Overview

Image preprocessing improves OCR accuracy by enhancing image quality before sending to the Vision API. This guide explains how to configure and use the preprocessing pipeline.

## Features

- **Contrast Enhancement:** Improves text visibility
- **Denoising:** Reduces image noise while preserving text
- **Sharpening:** Enhances text edges for better recognition
- **Resolution Optimization:** Ensures minimum resolution (1024×768) for best results
- **Background Normalization:** Improves contrast between text and background

## Configuration

Edit `v2/config/image-preprocessing.php` to configure preprocessing:

```php
return [
    'contrast' => [
        'enabled' => true,
        'factor' => 1.2, // 1.0 = no change, >1.0 = more contrast
        'method' => 'linear' // 'linear' or 'histogram'
    ],
    // ... other settings
];
```

## Enabling/Disabling

Set `OCR_PREPROCESSING_ENABLED` in `v2/config/image-preprocessing.php`:

```php
define('OCR_PREPROCESSING_ENABLED', true); // Enable
define('OCR_PREPROCESSING_ENABLED', false); // Disable
```

## Library Requirements

The system supports two image processing libraries:

1. **Imagick** (preferred): Better quality, more features
2. **GD** (fallback): Basic preprocessing if Imagick unavailable

Check availability:
```php
require_once 'v2/helpers/image-preprocessor.php';
$availability = checkPreprocessingAvailability();
// Returns: ['available' => bool, 'library' => 'imagick'|'gd'|'none']
```

## Expected Accuracy Improvement

- **Low-quality images:** 5-15% accuracy improvement
- **High-quality images:** 2-5% accuracy improvement
- **Processing overhead:** < 500ms per image

## Best Practices

1. **Enable for production:** Preprocessing improves accuracy with minimal cost
2. **Monitor performance:** Check processing times in logs
3. **Adjust parameters:** Fine-tune based on your image types
4. **Test before deploying:** Compare accuracy with/without preprocessing

## Troubleshooting

**Issue:** Preprocessing not working
- Check if GD or Imagick is installed: `php -m | grep -i gd` or `php -m | grep -i imagick`
- Check `OCR_PREPROCESSING_ENABLED` is `true`
- Review logs for preprocessing errors

**Issue:** Slow processing
- Reduce preprocessing options (disable deskewing if not needed)
- Use Imagick instead of GD for better performance
- Check image sizes (very large images take longer)

## Related Files

- `v2/helpers/image-preprocessor.php` - Preprocessing implementation
- `v2/config/image-preprocessing.php` - Configuration
- `v2/api/ocr-business-card.php` - Integration point