{"id":32719112,"url":"https://github.com/grandpaej/imgrs","last_synced_at":"2025-11-02T18:03:23.007Z","repository":{"id":318713331,"uuid":"1071247155","full_name":"GrandpaEJ/imgrs","owner":"GrandpaEJ","description":"Imgrs for Python. A blazingly fast, modern image processing library for Python. Powered by rust.","archived":false,"fork":false,"pushed_at":"2025-10-31T06:47:17.000Z","size":13915,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-31T07:27:25.485Z","etag":null,"topics":["image-processing","image-processing-python","imgrs","python-3","python3","rust"],"latest_commit_sha":null,"homepage":"https://grandpaej.github.io/imgrs/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrandpaEJ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-07T04:50:15.000Z","updated_at":"2025-10-31T06:47:20.000Z","dependencies_parsed_at":"2025-10-31T07:19:13.358Z","dependency_job_id":"2ef26f7b-3435-4414-9430-97bfdddee6fd","html_url":"https://github.com/GrandpaEJ/imgrs","commit_stats":null,"previous_names":["grandpaej/imgrs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/GrandpaEJ/imgrs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandpaEJ%2Fimgrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandpaEJ%2Fimgrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandpaEJ%2Fimgrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandpaEJ%2Fimgrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrandpaEJ","download_url":"https://codeload.github.com/GrandpaEJ/imgrs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrandpaEJ%2Fimgrs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282332561,"owners_count":26652047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-02T02:00:06.609Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-processing","image-processing-python","imgrs","python-3","python3","rust"],"created_at":"2025-11-02T18:02:38.216Z","updated_at":"2025-11-02T18:03:23.002Z","avatar_url":"https://github.com/GrandpaEJ.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Imgrs 🦀\n\n[![BUILD](https://github.com/grandpaej/imgrs/workflows/BUILD/badge.svg)](https://github.com/grandpaej/imgrs/actions)\n[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nImgrs 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.\n\n## 📚 Documentation\n\n- **[Quick Start Guide](docs/guides/quickstart.md)** - Get up and running in minutes\n- **[Basic Usage](docs/guides/basic-usage.md)** - Core concepts and common patterns\n- **[API Reference](docs/api/)** - Complete method documentation\n- **[Examples](docs/examples/README.md)** - Real-world usage examples\n- **[Migration Guide](docs/guides/migration.md)** - Migrating from Pillow\n\n## ✨ Key Features\n\n- **🔥 High Performance**: Significantly fast for common image operations\n- **🔄 Pillow Compatible**: Drop-in replacement for most Pillow operations\n- **🦀 Rust Powered**: Memory-safe and efficient core written in Rust\n- **📦 Easy to Use**: Simple, intuitive API that feels familiar\n- **🎯 Format Support**: PNG, JPEG, BMP, TIFF, GIF, WEBP\n\n## 🚀 Quick Start\n\n### Imgrs Installation\n\n```bash\npip install imgrs\n```\n\n### Basic Usage\n\n```python\nimport imgrs\n\n# Open an image\nimg = imgrs.open(\"photo.jpg\")\n\n# Resize image\nresized = img.resize((800, 600))\n\n# Crop image\ncropped = img.crop((100, 100, 500, 400))\n\n# Rotate image\nrotated = img.rotate(90)\n\n# Save image\nimg.save(\"output.png\")\n\n# to preview\nimg.show()\n\n# Create new image\nnew_img = imgrs.new(\"RGB\", (800, 600), \"red\")\n\n# Convert image modes\ngray_img = img.convert(\"L\")  # RGB to grayscale\nrgba_img = img.convert(\"RGBA\")  # Add alpha channel\n\n# Split image into channels\nr, g, b = img.split()  # RGB image -\u003e 3 grayscale images\n\n# Paste one image onto another\nbase = imgrs.new(\"RGB\", (200, 200), \"white\")\noverlay = imgrs.new(\"RGB\", (100, 100), \"red\")\nresult = base.paste(overlay, (50, 50))  # Paste at position (50, 50)\n\n# Create image from NumPy array (requires numpy)\nimport numpy as np\narray = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)\nimg_from_array = imgrs.fromarray(array)\n\n# Rich text rendering with styling\nimg = img.add_text(\"Hello World\", (50, 50), size=48, color=(255, 0, 0, 255))\n\n# Text with outline and shadow\nimg = img.add_text_styled(\n    \"BOLD TEXT\", \n    (100, 100), \n    size=64,\n    color=(255, 255, 255, 255),\n    outline=(0, 0, 0, 255, 3.0),\n    shadow=(3, 3, 0, 0, 0, 180)\n)\n\n# Centered text\nimg = img.add_text_centered(\"Centered Title\", 50, size=56, color=(0, 0, 128, 255))\n\n# Multi-line text\nmultiline = \"Line 1\\nLine 2\\nLine 3\"\nimg = img.add_text_multiline(multiline, (50, 50), size=32, line_spacing=1.5)\n\n# Measure text dimensions before rendering\nwidth, height = imgrs.Image.get_text_size(\"Sample Text\", size=48)\nprint(f\"Text will be {width}x{height} pixels\")\n\n# Get complete text bounding box information\nbox = imgrs.Image.get_text_box(\"Sample\", 100, 50, size=64)\nprint(f\"Text spans from ({box['x']}, {box['y']}) to ({box['right_x']}, {box['bottom_y']})\")\nprint(f\"Baseline at y={box['baseline_y']}\")\n```\n\n### Drop-in Pillow Replacement\n\n```python\n# Replace this:\n# from PIL import Image\n\n# With this:\nfrom imgrs import Image\n\n# Your existing Pillow code works unchanged!\nimg = Image.open(\"photo.jpg\")\nimg = img.resize((400, 300))\nimg.save(\"resized.jpg\")\n```\n\n## 🔄 Pillow Compatibility\n\n### ✅ Fully Compatible Operations\n\n- `open()`, `new()`, `save()`\n- `resize()`, `crop()`, `rotate()`, `transpose()`\n- `copy()`, `thumbnail()`\n- `convert()`, `paste()`, `split()` - **NEW!**\n- `fromarray()` - **NEW!** NumPy Integration\n- Properties: `size`, `width`, `height`, `mode`, `format`\n- All major image formats (PNG, JPEG, BMP, TIFF, GIF, WEBP)\n\n### 🎨 Image Filters - **NEW!**\n\n**Basic Filters:**\n- `blur()` - Gaussian blur with adjustable radius\n- `sharpen()` - Sharpening filter with adjustable strength\n- `edge_detect()` - Edge detection using Sobel operator\n- `emboss()` - Emboss effect\n- `brightness()` - Brightness adjustment\n- `contrast()` - Contrast adjustment\n\n**CSS-like Filters:**\n- `sepia()` - Sepia tone effect\n- `grayscale_filter()` - Grayscale conversion with amount control\n- `invert()` - Color inversion effect\n- `hue_rotate()` - Hue rotation in degrees\n- `saturate()` - Saturation adjustment\n\n**Filter chaining** - Combine multiple filters for complex effects\n\n### 🎯 Pixel Manipulation - **NEW!**\n\n- `getpixel()`, `putpixel()` - Direct pixel access and modification\n- `histogram()` - Color histogram analysis\n- `dominant_color()`, `average_color()` - Color analysis\n- `replace_color()` - Color replacement with tolerance\n- `threshold()` - Binary thresholding\n- `posterize()` - Color quantization\n\n### 🎨 Drawing Operations - **NEW!**\n\n- `draw_rectangle()` - Filled rectangles with alpha blending\n- `draw_circle()` - Filled circles with alpha blending\n- `draw_line()` - Lines using Bresenham's algorithm\n- `draw_text()` - Basic text rendering with bitmap fonts\n\n### ✨ Shadow Effects - **NEW!**\n\n- `drop_shadow()` - Drop shadow with blur and offset\n- `inner_shadow()` - Inner shadow effects\n- `glow()` - Glow effects with customizable intensity\n\n### 🚧 Planned Features\n\n- `frombytes()`, `tobytes()` - _Enhanced I/O_\n- Advanced text rendering with font support\n- Path operations and vector graphics\n- Additional blend modes and compositing operations\n\n## 📖 API Reference\n\n### Core Functions\n\n```python\n# Open image from file or bytes\nimg = imgrs.open(\"path/to/image.jpg\")\nimg = imgrs.open(image_bytes)\n\n# Create new image\nimg = imgrs.new(mode, size, color=None)\n# Examples:\nimg = imgrs.new(\"RGB\", (800, 600))  # Black image\nimg = imgrs.new(\"RGB\", (800, 600), \"red\")  # Red image\nimg = imgrs.new(\"RGB\", (800, 600), (255, 0, 0))  # Red image with RGB tuple\n```\n\n### Image Operations\n\n```python\n# Resize image\nresized = img.resize((width, height), resample=imgrs.Resampling.BILINEAR)\n\n# Crop image (left, top, right, bottom)\ncropped = img.crop((x1, y1, x2, y2))\n\n# Rotate image (90°, 180°, 270° supported)\nrotated = img.rotate(90)\n\n# Transpose/flip image\nflipped = img.transpose(imgrs.Transpose.FLIP_LEFT_RIGHT)\nflipped = img.transpose(imgrs.Transpose.FLIP_TOP_BOTTOM)\n\n# Copy image\ncopy = img.copy()\n\n# Create thumbnail (modifies image in-place)\nimg.thumbnail((200, 200))\n\n# Save image\nimg.save(\"output.jpg\", format=\"JPEG\")\nimg.save(\"output.png\")  # Format auto-detected from extension\nimg.show() # to preview \n```\n\n### Properties\n\n```python\n# Image dimensions\nwidth = img.width\nheight = img.height\nsize = img.size  # (width, height) tuple\n\n# Image mode and format\nmode = img.mode  # \"RGB\", \"RGBA\", \"L\", etc.\nformat = img.format  # \"JPEG\", \"PNG\", etc.\n\n# Raw pixel data\nbytes_data = img.to_bytes()\n```\n\n## 🔧 Development\n\n### Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/grandpaej/imgrs.git\ncd imgrs\n\n# Install dependencies\npip install -r requirements.txt\n\n# Build Rust extension\nmaturin develop --release\n\n# Run tests\npytest python/imgrs/tests/\n\n```\n\n### Requirements\n\n- Python 3.8+\n- Rust 1.70+\n- Maturin for building\n\n## 📖 Learn More\n\n### 🚀 Getting Started\n- **[Quick Start Guide](docs/guides/quickstart.md)** - Installation and first steps\n- **[Basic Usage](docs/guides/basic-usage.md)** - Essential concepts and patterns\n\n### 📚 Reference \u0026 Examples\n- **[API Reference](docs/api/)** - Complete method documentation\n- **[Examples](docs/examples/)** - Real-world usage examples\n- **[Performance Guide](docs/guides/)** - Optimization techniques\n\n### 🎯 Use Cases\n- **Photography**: Portrait enhancement, landscape processing, batch operations\n- **Web Development**: Image resizing, format optimization, thumbnail generation\n- **Creative Projects**: Artistic filters, collages, social media content\n- **Data Visualization**: Charts, infographics, dashboard creation\n- **E-commerce**: Product showcases, catalog generation, watermarking\n\n## 🤝 Contributing\n\n### Contributors\n\n- **[GrandpaEJ](https://github.com/GrandpaEJ)** - Feature requests and guidance\n- **[Bilal Tonga](https://github.com/bgunebakan/puhu)** - Initial implementation of the project\n\n\n### How to Contribute\n\nContributions are welcome! Areas where help is needed:\n\n1. **Medium Priority Features**: `getpixel()`, `putpixel()`, `frombytes()`\n2. **Performance Optimization**: Further speed improvements and benchmarking\n3. **Format Support**: Additional image formats and metadata handling\n4. **Advanced Operations**: CSS-like filters, path operations, text rendering\n5. **Documentation**: More examples and tutorials\n6. **Testing**: Edge cases, compatibility tests, and performance benchmarks\n\n## 📄 License\n\nApache Software License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [PyO3](https://pyo3.rs/) for Python-Rust integration\n- Uses [image-rs](https://github.com/image-rs/image) for core image processing\n- Inspired by [Pillow](https://pillow.readthedocs.io/) for API design\n- First Skaliton by [Bilal Tonga](https://github.com/bgunebakan/puhu)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrandpaej%2Fimgrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrandpaej%2Fimgrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrandpaej%2Fimgrs/lists"}