imgrs

Imgrs 🦀

Version 0.3.1 - Advanced text rendering has been re-added through the new TextMixin system, providing comprehensive text operations without external dependencies.

Imgrs is a blazingly fast, modern image processing library for Python, powered by Rust. Imgrs provides a Pillow-compatible API while delivering significantly better performance for common image operations.

📚 Documentation

• Quick Start Guide - Get up and running in minutes
• Basic Usage - Core concepts and common patterns
• API Reference - Complete method documentation
• Examples - Real-world usage examples
• Migration Guide - Migrating from Pillow

✨ Key Features

• 🔥 High Performance: Significantly fast for common image operations
• 🔄 Pillow Compatible: Drop-in replacement for most Pillow operations
• 🦀 Rust Powered: Memory-safe and efficient core written in Rust
• 📦 Easy to Use: Simple, intuitive API that feels familiar
• 🎯 Format Support: PNG, JPEG, BMP, TIFF, GIF, WEBP
• 🎨 65+ Filters: Comprehensive filter library (blur, sharpen, artistic effects)
• 🔧 Pixel Operations: Direct pixel manipulation and analysis
• 🎭 Drawing Tools: Shapes, lines, and advanced drawing operations
• 📝 Text Rendering: Advanced text operations with styling and effects - NEW!
• ⚡ Auto-Enhancement: Smart image optimization and color correction

🚀 Quick Start

Imgrs Installation

pip install imgrs

Basic Usage

import imgrs

# Open an image
img = imgrs.open("photo.jpg")

# Resize image
resized = img.resize((800, 600))

# Crop image
cropped = img.crop((100, 100, 500, 400))

# Rotate image
rotated = img.rotate(90)

# Save image
img.save("output.png")

# to preview
img.show()

# Create new image
new_img = imgrs.new("RGB", (800, 600), "red")

# Convert image modes
gray_img = img.convert("L")  # RGB to grayscale
rgba_img = img.convert("RGBA")  # Add alpha channel

# Split image into channels
r, g, b = img.split()  # RGB image -> 3 grayscale images

# Paste one image onto another
base = imgrs.new("RGB", (200, 200), "white")
overlay = imgrs.new("RGB", (100, 100), "red")
result = base.paste(overlay, (50, 50))  # Paste at position (50, 50)

# Create image from NumPy array (requires numpy)
import numpy as np
array = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
img_from_array = imgrs.fromarray(array)

# Apply filters for image enhancement
blurred = img.blur(2.0)
sharpened = img.sharpen(1.5)
sepia_tone = img.sepia()

# Pixel manipulation
pixel_color = img.getpixel((50, 50))
img.putpixel((50, 50), (255, 0, 0, 255))

# Color analysis
histogram = img.histogram()
dominant = img.dominant_color()
average = img.average_color()

# Drawing operations
img.draw_rectangle(10, 10, 100, 100, (255, 0, 0, 128))
img.draw_circle(150, 150, 50, (0, 255, 0, 128))
img.draw_line(0, 0, 200, 200, (0, 0, 255, 255))

# Text rendering
img.add_text("Hello World!", (20, 20), size=32, color=(0, 0, 0, 255))
img.add_text_styled("Styled Text", (20, 60), size=24, color=(255, 255, 255, 255),
                   outline=(0, 0, 0, 255, 1.0), background=(100, 149, 237, 255))
img.add_text_multiline("Multi-line\ntext example", (20, 100), size=18, color=(0, 100, 0, 255))

Drop-in Pillow Replacement

# Replace this:
# from PIL import Image

# With this:
from imgrs import Image

# Your existing Pillow code works unchanged!
img = Image.open("photo.jpg")
img = img.resize((400, 300))
img.save("resized.jpg")

🔄 Pillow Compatibility

✅ Fully Compatible Operations

• open(), new(), save()
• resize(), crop(), rotate(), transpose()
• copy(), thumbnail()
• convert(), paste(), split() - NEW!
• fromarray() - NEW! NumPy Integration
• Properties: size, width, height, mode, format
• All major image formats (PNG, JPEG, BMP, TIFF, GIF, WEBP)

🎨 Image Filters - NEW!

Basic Filters:

• blur() - Gaussian blur with adjustable radius
• sharpen() - Sharpening filter with adjustable strength
• edge_detect() - Edge detection using Sobel operator
• emboss() - Emboss effect
• brightness() - Brightness adjustment
• contrast() - Contrast adjustment

CSS-like Filters:

• sepia() - Sepia tone effect
• grayscale_filter() - Grayscale conversion with amount control
• invert() - Color inversion effect
• hue_rotate() - Hue rotation in degrees
• saturate() - Saturation adjustment

Filter chaining - Combine multiple filters for complex effects

🎯 Pixel Manipulation - NEW!

• getpixel(), putpixel() - Direct pixel access and modification
• histogram() - Color histogram analysis
• dominant_color(), average_color() - Color analysis
• replace_color() - Color replacement with tolerance
• threshold() - Binary thresholding
• posterize() - Color quantization

🎨 Drawing Operations - NEW!

• draw_rectangle() - Filled rectangles with alpha blending
• draw_circle() - Filled circles with alpha blending
• draw_line() - Lines using Bresenham's algorithm
• Shape generation: circle(), rectangle(), triangle(), ellipse(), star(), etc.

📝 Text Rendering - NEW!

• add_text() - Basic text rendering with flexible positioning
• add_text_styled() - Styled text with outlines, shadows, backgrounds, and opacity
• add_text_multiline() - Multi-line text with alignment and custom line spacing
• add_text_centered() - Horizontally centered text rendering
• get_text_dimensions() - Text size and metrics calculation
• get_multiline_text_dimensions() - Multi-line text dimensions with line count
• get_text_bounding_box() - Complete text bounding box with ascent/descent/baseline
• Convenience methods: add_text_with_shadow(), add_text_with_outline(), add_text_with_background()

🔤 Font Support - NEW!

• ImageFont.load() - Load TTF, OTF, WOFF, WOFF2 font files
• ImageFont.truetype() - Load TrueType fonts (Pillow-compatible)
• ImageFont.load_default() - Get default fallback font
• ImageFont.get_font() - Get font with automatic fallback
• text() - Pillow-compatible text drawing method

✨ Shadow Effects - NEW!

• drop_shadow() - Drop shadow with blur and offset
• inner_shadow() - Inner shadow effects
• glow() - Glow effects with customizable intensity

🚧 Planned Features

• frombytes(), tobytes() - Enhanced I/O
• Path operations and vector graphics
• Additional blend modes and compositing operations
• Arbitrary angle rotation support

📖 API Reference

Core Functions

# Open image from file or bytes
img = imgrs.open("path/to/image.jpg")
img = imgrs.open(image_bytes)

# Create new image
img = imgrs.new(mode, size, color=None)
# Examples:
img = imgrs.new("RGB", (800, 600))  # Black image
img = imgrs.new("RGB", (800, 600), "red")  # Red image
img = imgrs.new("RGB", (800, 600), (255, 0, 0))  # Red image with RGB tuple

Image Operations

# Resize image
resized = img.resize((width, height), resample=imgrs.Resampling.BILINEAR)

# Crop image (left, top, right, bottom)
cropped = img.crop((x1, y1, x2, y2))

# Rotate image (90°, 180°, 270° supported)
rotated = img.rotate(90)

# Transpose/flip image
flipped = img.transpose(imgrs.Transpose.FLIP_LEFT_RIGHT)
flipped = img.transpose(imgrs.Transpose.FLIP_TOP_BOTTOM)

# Copy image
copy = img.copy()

# Create thumbnail (modifies image in-place)
img.thumbnail((200, 200))

# Save image
img.save("output.jpg", format="JPEG")
img.save("output.png")  # Format auto-detected from extension
img.show() # to preview 

Properties

# Image dimensions
width = img.width
height = img.height
size = img.size  # (width, height) tuple

# Image mode and format
mode = img.mode  # "RGB", "RGBA", "L", etc.
format = img.format  # "JPEG", "PNG", etc.

# Raw pixel data
bytes_data = img.to_bytes()

Text Rendering

# Basic text rendering
img.add_text("Hello World!", (x, y), size=32, color=(0, 0, 0, 255))
img.add_text("Text", x, y, size=24, color=(255, 0, 0, 255))  # Separate x,y

# Styled text with effects
img.add_text_styled(
    "Styled Text",
    (x, y),
    size=28,
    color=(255, 255, 255, 255),
    outline=(0, 0, 0, 255, 2.0),      # Black outline, 2px width
    shadow=(3, 3, 128, 128, 128, 200), # Gray shadow, offset by 3px
    background=(100, 149, 237, 255),   # Blue background
    opacity=0.9
)

# Multi-line text
img.add_text_multiline(
    "Line 1\nLine 2\nLine 3",
    (x, y),
    size=20,
    color=(0, 0, 0, 255),
    align="center",      # "left", "center", or "right"
    line_spacing=1.5     # Line spacing multiplier
)

# Centered text
img.add_text_centered("Centered Text", y, size=32, color=(0, 0, 0, 255))

# Text measurement
width, height, ascent, descent = img.get_text_dimensions("Text", 24)
bbox = img.get_text_bounding_box("Text", x, y, 24)  # Returns dict with box info

# Convenience methods
img.add_text_with_shadow("Shadow Text", (x, y), size=24, color=(255, 0, 0, 255),
                        shadow_color=(0, 0, 0, 180), shadow_offset=(2, 2))
img.add_text_with_outline("Outlined", (x, y), size=20, color=(255, 255, 0, 255),
                         outline_color=(0, 0, 0, 255), outline_width=1.5)

🔧 Development

Building from Source

# Clone repository
git clone https://github.com/grandpaej/imgrs.git
cd imgrs

# Install dependencies
pip install -r requirements.txt

# Build Rust extension
maturin develop --release

# Run tests
pytest python/imgrs/tests/

Requirements

• Python 3.8+
• Rust 1.70+
• Maturin for building

📖 Learn More

🚀 Getting Started

• Quick Start Guide - Installation and first steps
• Basic Usage - Essential concepts and patterns

📚 Reference & Examples

• API Reference - Complete method documentation
• Examples - Real-world usage examples
• Performance Guide - Optimization techniques

🎯 Use Cases

• Photography: Portrait enhancement, landscape processing, batch operations
• Web Development: Image resizing, format optimization, thumbnail generation
• Creative Projects: Artistic filters, collages, social media content
• Data Visualization: Charts, infographics, dashboard creation
• E-commerce: Product showcases, catalog generation, watermarking

🤝 Contributing

Contributors

• GrandpaEJ - Feature requests and guidance
• Bilal Tonga - Initial implementation of the project

How to Contribute

Contributions are welcome! Areas where help is needed:

• Medium Priority Features: frombytes(), tobytes(), arbitrary angle rotation
• Performance Optimization: Further speed improvements and benchmarking
• Format Support: Additional image formats and metadata handling
• Advanced Operations: Path operations, vector graphics, additional blend modes
• Documentation: More examples and tutorials
• Testing: Edge cases, compatibility tests, and performance benchmarks

📄 License

Apache Software License - see LICENSE file for details.

🙏 Acknowledgments

• Built with PyO3 for Python-Rust integration
• Uses image-rs for core image processing
• Inspired by Pillow for API design
• First Skaliton by Bilal Tonga