README.md

---
license: apache-2.0
library_name: transformers
tags:
- image-processing
- medical-imaging
- fundus
- retinal-imaging
- diabetic-retinopathy
- ophthalmology
- clahe
- preprocessing
---

# EyeCLAHEImageProcessor

A GPU-native Hugging Face ImageProcessor for **Color Fundus Photography (CFP)** images, designed for diabetic retinopathy detection and other retinal imaging tasks.

## Features

- **Eye Region Localization**: Automatically detects and centers on the fundus using gradient-based radial symmetry
- **Smart Cropping**: Border-minimized square crop centered on the detected eye
- **CLAHE Enhancement**: Contrast Limited Adaptive Histogram Equalization for improved visibility
- **Pure PyTorch**: No OpenCV/PIL dependencies at runtime - fully GPU-accelerated
- **Batch Processing**: Efficient batched operations for training pipelines
- **Flexible Input**: Accepts PyTorch tensors, PIL Images, and NumPy arrays

## Installation

```bash
pip install transformers torch
```

## Quick Start

```python
from transformers import AutoImageProcessor
from PIL import Image

# Load the processor
processor = AutoImageProcessor.from_pretrained("iszt/eye-clahe-processor", trust_remote_code=True)

# Process a single image
image = Image.open("fundus_image.jpg")
outputs = processor(image, return_tensors="pt")
pixel_values = outputs["pixel_values"]  # Shape: (1, 3, 512, 512)

# Process on GPU
outputs = processor(image, return_tensors="pt", device="cuda")
```

## Batch Processing

```python
import torch
from PIL import Image

# Load multiple images
images = [Image.open(f"image_{i}.jpg") for i in range(8)]

# Process batch
outputs = processor(images, return_tensors="pt", device="cuda")
pixel_values = outputs["pixel_values"]  # Shape: (8, 3, 512, 512)
```

## With PyTorch Tensors

```python
import torch

# Tensor input: (B, C, H, W) or (C, H, W)
images = torch.rand(4, 3, 512, 512)  # Batch of 4 images

outputs = processor(images, return_tensors="pt")
```

## Configuration Options

| Parameter | Default | Description |
|-----------|---------|-------------|
| `size` | 512 | Output image size (square) |
| `do_crop` | true | Enable eye-centered cropping |
| `do_clahe` | true | Enable CLAHE contrast enhancement |
| `crop_scale_factor` | 1.1 | Padding around detected eye region |
| `clahe_grid_size` | 8 | CLAHE tile grid size |
| `clahe_clip_limit` | 2.0 | CLAHE histogram clip limit |
| `normalization_mode` | "imagenet" | Normalization: "imagenet", "none", or "custom" |
| `min_radius_frac` | 0.1 | Minimum eye radius as fraction of image |
| `max_radius_frac` | 0.9 | Maximum eye radius as fraction of image |
| `allow_overflow` | true | Allow crop box beyond image bounds (fills with black) |
| `softmax_temperature` | 0.3 | Temperature for eye center detection (higher = smoother) |

## Custom Configuration

```python
from transformers import AutoImageProcessor

processor = AutoImageProcessor.from_pretrained(
    "iszt/eye-clahe-processor",
    trust_remote_code=True,
    size=384,
    normalization_mode="imagenet",
    clahe_clip_limit=3.0,
    softmax_temperature=0.3,
)
```

## Processing Pipeline

The processor applies the following steps:

1. **Input Standardization**: Convert PIL/NumPy/Tensor to (B, C, H, W) float32 tensor in [0, 1]
2. **Eye Localization**: Detect fundus center using radial symmetry analysis
3. **Radius Estimation**: Determine fundus boundary from radial intensity profiles
4. **Crop & Resize**: Extract square region centered on eye, resize to target size
5. **CLAHE**: Apply contrast enhancement in LAB color space (L channel only)
6. **Normalization**: Apply ImageNet normalization (optional)

## Use with Vision Models

```python
from transformers import AutoImageProcessor, AutoModel
from PIL import Image

# Load processor and model
processor = AutoImageProcessor.from_pretrained("iszt/eye-clahe-processor", trust_remote_code=True)
model = AutoModel.from_pretrained("google/vit-base-patch16-224")

# Process and run inference
image = Image.open("fundus.jpg")
inputs = processor(image, return_tensors="pt", device="cuda")

# Update normalization for pretrained models
inputs["pixel_values"] = (inputs["pixel_values"] - torch.tensor([0.485, 0.456, 0.406]).view(1,3,1,1).cuda()) / torch.tensor([0.229, 0.224, 0.225]).view(1,3,1,1).cuda()

with torch.no_grad():
    outputs = model(**inputs)
```

## Coordinate Mapping

The processor returns coordinate mapping information that allows you to map coordinates from the processed image back to the original image space. This is useful for applications like lesion detection, where you need to annotate or visualize detected features on the original image.

### Output Format

The processor returns these additional keys:
- `scale_x`, `scale_y`: Scale factors for coordinate mapping (shape: `(B,)`)
- `offset_x`, `offset_y`: Offset values for coordinate mapping (shape: `(B,)`)

### Mapping Formula

To map coordinates from the processed image back to original coordinates:

```python
orig_x = offset_x + cropped_x * scale_x
orig_y = offset_y + cropped_y * scale_y
```

Where `cropped_x` and `cropped_y` are coordinates in the processed image (range: [0, size-1]).

### Example: Single Point Mapping

```python
from PIL import Image

# Process image
processor = AutoImageProcessor.from_pretrained("iszt/eye-clahe-processor", trust_remote_code=True)
image = Image.open("fundus.jpg")
outputs = processor(image, return_tensors="pt")

# Detected point in processed image (e.g., from a model prediction)
detected_x, detected_y = 100.0, 150.0

# Map back to original image coordinates
orig_x = outputs['offset_x'] + detected_x * outputs['scale_x']
orig_y = outputs['offset_y'] + detected_y * outputs['scale_y']

print(f"Original coordinates: ({orig_x.item():.2f}, {orig_y.item():.2f})")
```

### Example: Multiple Points in Batch

```python
import torch

# Process batch of images
images = [Image.open(f"image_{i}.jpg") for i in range(4)]
outputs = processor(images, return_tensors="pt")

# Detected points for each image (B, N, 2) where N is number of points
detected_points = torch.tensor([
    [[50.0, 60.0], [100.0, 120.0]],  # Image 0: 2 points
    [[75.0, 80.0], [150.0, 160.0]],  # Image 1: 2 points
    [[90.0, 95.0], [180.0, 190.0]],  # Image 2: 2 points
    [[65.0, 70.0], [130.0, 140.0]],  # Image 3: 2 points
])

# Map all points back to original coordinates
B, N, _ = detected_points.shape
scale_x = outputs['scale_x'].view(B, 1, 1)
scale_y = outputs['scale_y'].view(B, 1, 1)
offset_x = outputs['offset_x'].view(B, 1, 1)
offset_y = outputs['offset_y'].view(B, 1, 1)

orig_x = offset_x + detected_points[..., 0:1] * scale_x
orig_y = offset_y + detected_points[..., 1:2] * scale_y

original_points = torch.cat([orig_x, orig_y], dim=-1)  # (B, N, 2)
```

### Use Cases

- **Lesion Detection**: Map detected lesion coordinates back for visualization
- **Optic Disc Localization**: Track anatomical landmarks through preprocessing
- **Vessel Segmentation**: Align segmentation masks with original images
- **Quality Control**: Verify feature alignment across processing pipeline

## Technical Details

### Eye Center Detection

Uses a gradient-based radial symmetry approach:
- Computes Sobel gradients to detect edges
- Finds circular boundaries where gradients point inward radially
- Weights by edge strength and proximity to dark regions (background)
- Uses soft argmax for sub-pixel accuracy

### CLAHE Implementation

Pure PyTorch CLAHE with:
- Proper sRGB to CIE LAB conversion
- Vectorized histogram computation using scatter_add
- Bilinear interpolation between tile CDFs
- Only modifies L channel, preserving color information

## License

Apache 2.0

## Citation

If you use this processor in your research, please cite:

```bibtex
@software{eye_clahe_processor,
  title={EyeCLAHEImageProcessor: GPU-Native Fundus Image Preprocessing},
  year={2026},
  url={https://huggingface.co/iszt/eye-clahe-processor}
}
```