imgshift 0.1.2

Fast image conversion library with exceptional SVG support

imgshift

Shift between any image format effortlessly.

A high-performance Python library for universal image format conversion with exceptional SVG support. Features dual-engine SVG rendering (production-grade resvg + pure-Python fallback) and supports all major image formats.

Features

• 🎨 Universal Format Support: Convert between PNG, JPEG, WebP, GIF, BMP, TIFF, ICO, SVG, and PDF
• � Dual-Engine SVG Rendering: Production-grade resvg engine with pure-Python fallback
• 🔧 Flexible Engine Selection: Choose between auto (smart fallback), resvg (production), or python (experimental)
• 📐 Smart Upscaling: Lanczos/bicubic/bilinear interpolation for high-quality image scaling
• 📄 PDF Support: Convert images to/from PDF, combine multiple images into multi-page PDFs
• 🔧 Flexible API: Simple one-liner functions or fluent method chaining
• 💻 CLI Tool: Command-line interface with engine selection support

Installation

pip install imgshift

This installs all dependencies including resvg-py for production-grade SVG rendering.

Quick Start

Simple Conversion

from imgshift import convert

# SVG to PNG (uses best available engine)
convert("icon.svg", "icon.png")

# With specific size
convert("icon.svg", "icon.png", width=512)

# Use specific SVG engine
convert("logo.svg", "logo.png", engine="resvg")  # Production quality
convert("simple.svg", "simple.png", engine="python")  # Zero dependencies

# PNG to JPEG with quality
convert("photo.png", "photo.jpg", quality=90)

# PDF page to PNG
convert("document.pdf", "page.png", page=0, dpi=300)

Fluent API

from imgshift import Image

# Chain operations
Image("icon.svg").resize(512, 512).save("icon.png")

# With quality and DPI settings
Image("photo.png").set_quality(95).set_dpi(150).save("photo.jpg")

# PDF with specific page
Image("document.pdf").page(0).set_dpi(300).save("page.png")

Multiple Images to PDF

from imgshift import convert

# Combine multiple images into a PDF
convert(["page1.png", "page2.png", "page3.png"], "document.pdf")

CLI Usage

# Single file conversion
imgshift input.svg output.png

# With options
imgshift input.svg output.png --width 512 --height 512

# Choose SVG engine
imgshift logo.svg logo.png --engine resvg  # Production quality
imgshift icon.svg icon.png --engine python  # Pure Python

# Batch conversion
imgshift *.svg --to png --output-dir ./converted

# Multiple files to PDF
imgshift img1.png img2.png img3.png -o output.pdf

CLI Options

Option	Description
--width, -w	Output width in pixels
--height, -H	Output height in pixels
--quality, -q	JPEG/WebP quality (1-100, default: 85)
--dpi, -d	DPI for PDF/SVG rendering (default: 150)
--page, -p	PDF page number (0-indexed)
--engine	SVG engine: auto, resvg, or python
--to, -t	Target format for batch conversion
--output-dir, -o	Output directory

Supported Formats

Format	Read	Write	Notes
PNG	✅	✅	Lossless with alpha channel
JPEG	✅	✅	Lossy compression, quality 1-100
WebP	✅	✅	Modern format, lossy/lossless
GIF	✅	✅	Palette-based, 256 colors
BMP	✅	✅	Uncompressed bitmap
TIFF	✅	✅	High-quality, supports compression
ICO	✅	✅	Windows icon format
SVG	✅	❌	Vector graphics (custom renderer)
PDF	✅	✅	Single or multi-page documents

SVG Rendering

imgshift uses a dual-engine architecture for SVG rendering:

Primary Engine: resvg (Production)

The resvg engine (installed by default) provides:

• ✅ Full SVG 1.1 specification compliance
• ✅ Complex gradients, patterns, and filters
• ✅ Advanced path operations and clipping
• ✅ Production-grade accuracy (used by major tools)
• ✅ Rust-powered performance

Default: Used automatically for best quality.

Fallback Engine: python (Experimental)

The pure-Python engine provides:

• ✅ Zero external dependencies (if you uninstall resvg-py)
• ✅ Basic SVG shapes and paths
• ✅ Transforms and styling
• ⚠️ Limited support for advanced features
• ⚠️ May have rendering artifacts on complex SVGs

Use when: You need to avoid compiled dependencies or rendering very simple SVGs.

Engine Selection

# Auto mode (default): tries resvg, falls back to python
convert("logo.svg", "logo.png", engine="auto")

# Explicit resvg (production)
convert("complex.svg", "complex.png", engine="resvg")

# Explicit python (zero dependencies)
convert("simple.svg", "simple.png", engine="python")

Default behavior: resvg is used automatically. You can explicitly choose the pure-Python engine if needed.

Supported SVG Features

Python Engine Support

Shapes

• <rect> - Rectangles (including rounded corners)
• <circle> - Circles
• <ellipse> - Ellipses
• <line> - Lines
• <polyline> - Connected line segments
• <polygon> - Closed polygons
• <path> - Full path syntax including curves
• <text> - Basic text rendering

Path Commands

• Move: M, m
• Line: L, l, H, h, V, v
• Cubic Bezier: C, c, S, s
• Quadratic Bezier: Q, q, T, t
• Arc: A, a
• Close: Z, z

Styling

• fill - Fill color (hex, named colors, rgb/rgba)
• stroke - Stroke color
• stroke-width - Stroke width
• opacity - Element opacity
• fill-opacity - Fill opacity
• stroke-opacity - Stroke opacity

Transforms

• translate(x, y)
• rotate(angle) or rotate(angle, cx, cy)
• scale(x) or scale(x, y)
• skewX(angle) / skewY(angle)
• matrix(a, b, c, d, e, f)

API Reference

convert(source, target, **options)

Convert an image from one format to another.

Parameters:

• source: Source file path (str or Path), or list of paths for multi-image PDF
• target: Target file path
• width: Target width (optional)
• height: Target height (optional)
• quality: JPEG/WebP quality 1-100 (default: 85)
• dpi: DPI for PDF/SVG rendering (default: 150)
• page: PDF page number, 0-indexed (optional)
• background: Background color tuple (R, G, B, A) for SVG (default: white)
• engine: SVG rendering engine: "auto", "resvg", or "python" (default: "auto")

Image(source)

Fluent API for image manipulation.

Methods:

• .resize(width, height) - Set target dimensions
• .set_quality(quality) - Set JPEG/WebP quality
• .set_dpi(dpi) - Set DPI for PDF/SVG
• .page(page_num) - Select PDF page
• .set_background(r, g, b, a) - Set SVG background color
• .save(dest) - Save to file

Dependencies

• pypng - Pure Python PNG handling
• Pillow - JPEG and other raster formats
• PyMuPDF - PDF reading and writing
• resvg-py - Production-grade SVG rendering

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with ❤️ for the Python community.