iszt/eye-clahe-processor

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

pip install transformers torch

Quick Start

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

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

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

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

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:

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

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

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:

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