image-converter

```python

from PIL import Image

import pillow_heif

# Register HEIF/HEIC support

pillow_heif.register_heif_opener()

img = Image.open("input.heic")

img.save("output.jpg", quality=85, optimize=True)

```

```bash

pip install pillow pillow-heif

```

Supported Formats

| Format | Read | Write | Notes |

|--------|------|-------|-------|

| JPEG/JPG | Yes | Yes | Lossy, best for photos |

| PNG | Yes | Yes | Lossless, supports transparency |

| WebP | Yes | Yes | Modern web format, excellent compression |

| HEIC/HEIF | Yes | No* | Apple format, requires pillow-heif |

| GIF | Yes | Yes | Animation support |

| TIFF | Yes | Yes | Lossless, large files |

| BMP | Yes | Yes | Uncompressed |

| AVIF | Yes | Yes* | Best compression, requires pillow-avif-plugin |

*Limited support, check library versions

Mode Conversion

```python

# RGBA (with alpha) -> RGB (for JPEG)

if img.mode in ('RGBA', 'LA', 'P'):

img = img.convert('RGB')

# RGB -> Grayscale

gray = img.convert('L')

# Grayscale -> RGB

rgb = gray.convert('RGB')

```

Proportional Resize

```python

# Resize by percentage

scale = 0.5 # 50%

new_size = (int(img.width scale), int(img.height scale))

resized = img.resize(new_size, Image.LANCZOS)

# Resize to max dimension (preserve aspect ratio)

max_dim = 1920

ratio = min(max_dim / img.width, max_dim / img.height)

if ratio < 1:

new_size = (int(img.width ratio), int(img.height ratio))

resized = img.resize(new_size, Image.LANCZOS)

```

Thumbnail (in-place, efficient)

```python

img.thumbnail((800, 800), Image.LANCZOS) # Modifies in-place

```

Resampling Filters

• Image.LANCZOS - Best quality, slower (recommended for downscaling)
• Image.BICUBIC - Good quality, faster
• Image.BILINEAR - Medium quality
• Image.NEAREST - Fastest, pixelated (good for pixel art)

JPEG Quality

```python

# Quality 1-100 (80-85 is good balance)

img.save("out.jpg", quality=85, optimize=True)

# Progressive JPEG (loads gradually)

img.save("out.jpg", quality=85, optimize=True, progressive=True)

```

PNG Optimization

```python

# Maximum compression

img.save("out.png", optimize=True, compress_level=9)

# Reduce colors for smaller file (256 colors max)

quantized = img.quantize(colors=256)

quantized.save("out.png", optimize=True)

```

WebP (best for web)

```python

# Lossy (like JPEG)

img.save("out.webp", quality=85, method=6)

# Lossless (like PNG but smaller)

img.save("out.webp", lossless=True, quality=100)

```

See scripts/batch_convert.py for full batch processing with:

• Parallel processing with concurrent.futures
• Progress reporting
• Error handling
• Multiple output formats

Basic Batch Pattern

```python

from pathlib import Path

from concurrent.futures import ThreadPoolExecutor

def convert_image(path, output_dir, target_format, quality=85):

img = Image.open(path)

if img.mode != 'RGB':

img = img.convert('RGB')

output = output_dir / f"{path.stem}.{target_format}"

img.save(output, quality=quality, optimize=True)

return output

input_dir = Path("./images")

output_dir = Path("./converted")

output_dir.mkdir(exist_ok=True)

files = list(input_dir.glob("*.png"))

with ThreadPoolExecutor(max_workers=4) as executor:

results = list(executor.map(

lambda f: convert_image(f, output_dir, "jpg"),

files

))

```

Strip All Metadata

```python

# Create clean image (removes ALL metadata including ICC profile)

clean = Image.new(img.mode, img.size)

clean.putdata(list(img.getdata()))

clean.save("clean.jpg", quality=85)

```

Strip EXIF Only (preserve ICC color profile)

```python

icc = img.info.get('icc_profile')

if 'exif' in img.info:

del img.info['exif']

img.save("out.jpg", quality=85, icc_profile=icc)

```

Handle EXIF Orientation

```python

from PIL import ImageOps

img = ImageOps.exif_transpose(img) # Auto-rotate based on EXIF

```

```python

from PIL import Image, ImageDraw, ImageFont

def add_watermark(img, text, opacity=128):

watermark = Image.new('RGBA', img.size, (0, 0, 0, 0))

draw = ImageDraw.Draw(watermark)

# Use default font or specify path

try:

font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 36)

except:

font = ImageFont.load_default()

bbox = draw.textbbox((0, 0), text, font=font)

text_width = bbox[2] - bbox[0]

text_height = bbox[3] - bbox[1]

x = img.width - text_width - 20

y = img.height - text_height - 20

draw.text((x, y), text, font=font, fill=(255, 255, 255, opacity))

if img.mode != 'RGBA':

img = img.convert('RGBA')

return Image.alpha_composite(img, watermark)

```

HEIC to JPEG (iPhone photos)

```python

import pillow_heif

pillow_heif.register_heif_opener()

img = Image.open("photo.heic")

img = ImageOps.exif_transpose(img) # Fix orientation

if img.mode != 'RGB':

img = img.convert('RGB')

img.save("photo.jpg", quality=85, optimize=True)

```

Optimize for Web

```python

def optimize_for_web(input_path, output_path, max_width=1920, quality=85):

img = Image.open(input_path)

img = ImageOps.exif_transpose(img)

# Resize if too large

if img.width > max_width:

ratio = max_width / img.width

new_size = (max_width, int(img.height * ratio))

img = img.resize(new_size, Image.LANCZOS)

# Convert mode

if img.mode in ('RGBA', 'P'):

img = img.convert('RGB')

# Strip metadata

icc = img.info.get('icc_profile')

# Save optimized

img.save(output_path, quality=quality, optimize=True,

progressive=True, icc_profile=icc)

```

Create Thumbnails

```python

def create_thumbnail(input_path, output_path, size=(300, 300)):

img = Image.open(input_path)

img = ImageOps.exif_transpose(img)

img.thumbnail(size, Image.LANCZOS)

if img.mode != 'RGB':

img = img.convert('RGB')

img.save(output_path, quality=85, optimize=True)

```

| Format | Typical Size | Best For |

|--------|-------------|----------|

| JPEG 85% | 100% baseline | Photos |

| WebP 85% | ~30% smaller | Web images |

| PNG | 2-5x larger | Graphics with transparency |

| AVIF 85% | ~50% smaller | Next-gen web |

| HEIC | ~50% smaller | Apple ecosystem |

• scripts/batch_convert.py - Full-featured batch converter with CLI
• scripts/optimize_web.py - Web optimization with size targets