You can deploy this model and start earning money today!

iszt/
eye-clahe-processor

Views

No views yet

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

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:

Input Standardization: Convert PIL/NumPy/Tensor to (B, C, H, W) float32 tensor in [0, 1]
Eye Localization: Detect fundus center using radial symmetry analysis
Radius Estimation: Determine fundus boundary from radial intensity profiles
Crop & Resize: Extract square region centered on eye, resize to target size
CLAHE: Apply contrast enhancement in LAB color space (L channel only)
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}
}