• Stars
    star
    4,154
  • Rank 10,424 (Top 0.3 %)
  • Language
    Rust
  • License
    GNU Affero Genera...
  • Created about 10 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

High-performance image manipulation for web servers. Includes imageflow_server, imageflow_tool, and libimageflow

imageflow optimal images at incredible speeds

tests state: release candidate

Docker Pulls view releases license: Choose AGPLv3 or Commercial

Download blazing fast and safer tools for a modern image workflow.

  • imageflow_tool is a command-line tool for experimenting, running batch jobs, JSON jobs, or when you want process isolation. Up to 17x faster than ImageMagick. Also produces smaller files at higher quality.
  • libimageflow is for direct (in-process) use from your programming language. See our Node bindings, Go bindings, Scala bindings, Elixir bindings, or .NET bindings. If we don't already have bindings for your language, consider spending a day to add them. Imageflow has a simple C-compatible ABI, of which only 4 methods are needed to implement bindings.
  • Imageflow.Server is cross-platform and can manipulate images in-flight (e.g./bucket/img.jpg?w=200) for direct use from HTML. Source images can reside in blob storage, on another server, or on the filesystem. It's a production ready server with excellent hybrid disk caching, support for Azure and Amazon blob storage, and can be easily customized. You can deploy it easily via Docker, on a VM, or via any cloud host. It's also backwards compatible with the ImageResizer API - which is useful, as ImageResizer as been integrated into more than a thousand different CMSes and applications in the last decade.

Open an issue to share ideas, feedback, or ask questions. We believe in feedback-driven design, and streamlining real-world usage is the fastest way to a great product.

Querystring API Documentation

JSON API Documentation

libimageflow and imageflow_tool are available as self-contained binaries for Windows, Ubuntu, and Mac. We also offer Docker images for Linux (where glibc and OpenSSL are required).

We thank our backers on Kickstarter and the many supporters of ImageResizer for making this project a reality. Visit Imageresizing.net if you need an AGPLv3 exception for commercial use.

Start with imageflow_tool (recommended)

imageflow_tool examples --generate - creates an examples directory with JSON jobs and invocation scripts.

You can use command strings that are compatible with ImageResizer 4 querystrings:

imageflow_tool v1/querystring --in source.jpg --out thumb.jpg --command "width=50&height=50&mode=crop&format=jpg"

Or submit a JSON job file. JSON jobs can have multiple inputs and outputs, and can represent any kind of operation graph.

The following generates multiple sizes of an image from an example job file:

imageflow_tool v1/build --json examples/export_4_sizes/export_4_sizes.json
        --in waterhouse.jpg
        --out 1 waterhouse_w1600.jpg
              2 waterhouse_w1200.jpg
              3 waterhouse_w800.jpg
              4 waterhouse_w400.jpg
        --response operation_result.json

By default, imageflow_tool prints a JSON response to stdout. You write this to disk with --response.

--debug-package will create a .zip file to reproduce problematic behavior with both v1/build and v1/querystring. Please submit bug reports; we try to make it easy.

Using Imageflow.Server for dynamic imaging

NOTE: imageflow_server has been removed as the underlying web framework (iron) is abandoned and no longer secure. For the last few years we have suggested moving to the production-ready Imageflow.Server product, which also offers docker deployment (but we suggest your own dockerfile to permit configuration)

Now you can edit images from HTML... and use srcset without headache.

<img src="http://localhost:39876/demo_images/u3.jpg?w=300" />

<img src="" srcset="    http://localhost:39876/demo_images/u3.jpg?w=300 300w
                        http://localhost:39876/demo_images/u3.jpg?w=800 800w
                        http://localhost:39876/demo_images/u3.jpg?w=1600 1600w" />

Beyond the demo

You'll want to mount various image source locations to prefixes. The --mount command parses a colon (:) delimited list of arguments. The first is the prefix you'll use in the URL (like http://localhost:39876/prefix/. The second is the engine name. Remaining arguments are sent to the engine.

Examples

  • --mount "/img/:ir4_local:C:\inetpub\wwwroot\images"
  • --mount "/proxyimg/:ir4_http:https:://myotherserver.com/imagefolder/" (note the double escaping of the colon)
  • --mount "/cachedstaticproxy/:permacache_proxy:https:://othersite.com"
  • --mount "/githubproxy/:permacache_proxy_guess_content_types:https:://raw.github.com/because/it/doesnt/support/content/types"
  • --mount "/static/":static:./assets"

Using libimageflow from your language

You also may find that imageflow_tool is quite fast enough for your needs.

Crates within this project

  • imageflow_abi - The stable API of libimageflow/imageflow.dll. Headers for libimageflow are located in bindings/headers
  • imageflow_tool - The command-line tool
  • imageflow_server - The HTTP server
  • c_components - A rust crate containing C source
  • c_components/tests - Tests for the C components
  • imageflow_types - Shared types used by most crates, with JSON serialization
  • imageflow_helpers - Common helper functions and utilities
  • imageflow_riapi - RIAPI and ImageResizer4 compatibility parsing/layout
  • imageflow_core - The main library and execution engine

Known flaws and missing features (as of May 2020)

Flaws

  • imageflow_server doesn't expose the JSON API yet.
  • No fuzz testing or third-party auditing yet.

Missing features

  • Blurring.

Delayed features

  • Job cost prediction (delayed - no interest from community)

Building from Source without Docker

You'll need more than just Rust to compile Imageflow, as it has a couple C dependencies.

  1. Install platform-specific prerequisites (find the right section below).
  2. Clone and cd into this repository E.g., git clone [email protected]:imazen/imageflow.git && cd imageflow)

If you are using bash on any platform, you should be able to use build.sh

  • ./build.sh clean - to clean
  • ./build.sh test - run all tests
  • ./build.sh debug - generate slow debug binaries
  • ./build.sh release - generate release binaries
  • ./build.sh install - install release binaries to /usr/local (must run `./build.sh release first)
  • ./build.sh uninstall - uninstall release binaries

build.sh places binaries in the ./artifacts/ directory

If you are on Windows, only run build commands in the window created by win_enter_env.bat.

You can also build using cargo directly, although this will place binaries in ./target/release instead. * cargo test --all to test Imageflow in debug (slooow) mode * cargo build --package imageflow_abi --release to compile libimageflow/imageflow.dll * cargo build --package imageflow_tool --release to compile imageflow_tool(.exe) * cargo build --all --release to compile everything in release mode * cargo doc --no-deps --all --release to generate documentation.

Building from Source with Docker

Note that we no longer use docker containers for CI, so this method is outdated.

  1. Install Docker
  2. Run from a bash session (Docker + Windows WSL, macOS, or linux)
  3. git clone [email protected]:imazen/imageflow.git
    cd imageflow
    ./build_via_docker.sh debug

This will create caches within ~/.docker_imageflow_caches specific to the docker image used. Instances will be ephemeral; the only state will be in the caches.

The official Dockerfiles are also a great place to get more detailed environment setup steps, as we don't list steps for setting up:

  • Valgrind (common versions break openssl; you may need to build from source)
  • Code coverage
  • Bindings.

Linux Pre-requisites

(tested on Ubuntu 20.04 and 22.04.)

#Install Rust by running
`curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable`
#Ensure build tools are installed (git, curl, wget, gcc, g++, nasm, pkg-config, openssl, ca-certificates)
`sudo apt-get install git wget curl build-essential pkg-config libssl-dev libpng-dev nasm `

Mac OS Pre-requisites

  1. Install XCode Command-Line Tools if you haven't already
  2. Install Homebrew if you haven't already.
  3. Install nasm, pkg-config, and wget brew install nasm pkg-config wget
  4. Install Rust

Windows WSL (Ubuntu) Pre-requisites

  1. Install Ubuntu from the Windows Store
  2. Run Ubuntu 22.04 and create your username/password
  3. sudo apt-get update to update available packages.
  4. Install Rust by running curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
  5. Ensure build tools are installed (git, curl, wget, gcc, g++, nasm, pkg-config, openssl, ca-certificates) sudo apt-get install git wget curl build-essential pkg-config libssl-dev libpng-dev nasm
  6. (optional) To use a graphical text editor, you'll need to download imageflow to a "Windows" directory, then map it to a location in Ubuntu. For example, if you cloned imageflow to Documents/imageflow, you would run: ln -s /mnt/c/Users/[YourWindowsUserName]/Documents/imageflow ~/win_imageflow
  7. Close and re-open Ubuntu

Windows 10 Pre-requisites

  1. Install Visual Studio 2017 Build Tools (separately or as a VS component)
  2. Install Git 64-bit.
  3. Run As Administrator the NASM 64-bit installer - it will not prompt.
  4. Install Rust 64-bit if you want 64-bit Imageflow or Rust 32-bit if you don't. Install toolchain stable as the default, and confirm adding it to PATH.
  5. Open the command line and switch to this repository's root directory
  6. Edit ci/wintools/SETUP_PATH.bat to ensure that rust/cargo, nasm, git, and Git/mingw64/bin are all in %PATH%.
  7. Run win_enter_env.bat to start a sub-shell (edit it if you want a 32-bit build)
  8. All build commands should be run in the sub-shell. Run cmd.exe /c "ci\wintools\win_verify_tools.bat" to check tools are present.

How does one learn image processing for the web?

First, read High Performance Images for context.

There are not many great textbooks on the subject. Here are some from my personal bookshelf. Between them (and Wikipedia) I was able to put together about 60% of the knowledge I needed; the rest I found by reading the source code to many popular image processing libraries.

I would start by reading Principles of Digital Image Processing: Core Algorithms front-to-back, then Digital Image Warping. Wikipedia is also a useful reference, although the relevant pages are not linked or categorized together - use specific search terms, like "bilinear interpolation" and "Lab color space".

I have found the source code for OpenCV, LibGD, FreeImage, Libvips, Pixman, Cairo, ImageMagick, stb_image, Skia, and FrameWave is very useful for understanding real-world implementations and considerations. Most textbooks assume an infinite plane, ignore off-by-one errors, floating-point limitations, color space accuracy, and operational symmetry within a bounded region. I cannot recommend any textbook as an accurate reference, only as a conceptual starting point. I made some notes regarding issues to be aware of when creating an imaging library.

Also, keep in mind that computer vision is very different from image creation. In computer vision, resampling accuracy matters very little, for example. But in image creation, you are serving images to photographers, people with far keener visual perception than the average developer. The images produced will be rendered side-by-side with other CSS and images, and the least significant bit of inaccuracy is quite visible. You are competing with Lightroom; with offline tools that produce visually perfect results. End-user software will be discarded if photographers feel it is corrupting their work.

More Repositories

1

resizer

The official repository for ImageResizer
C#
567
star
2

imageflow-dotnet-server

A super-fast image server to speed up your site - deploy as a microservice, serverless, or embeddable.
C#
248
star
3

slimmage

Context-friendly responsive image solution
JavaScript
167
star
4

imageflow-dotnet

The official .NET API for Imageflow, the Rust image processing and optimization engine for web servers
C#
142
star
5

libwebp-net

A .NET wrapper for libwebp
C#
136
star
6

studiojs

[Deprecated] A set of jQuery plugins that compose a flexible, web-based image editing studio.
JavaScript
92
star
7

imageflow-node

An Image manipulation Library for Nodejs. Based on https://github.com/imazen/imageflow
TypeScript
87
star
8

Graphics-vNext

The future of server-side graphics in ASP.NET
C#
68
star
9

keyhub

License management portal from Imazen & Lucrasoft. Looking for new maintainer (has been replaced by Chargebee, S3, & a ruby script)
C#
52
star
10

reunion

Repeatable, evidence-based expense and income accounting
Ruby
39
star
11

freeimage

DEPRECATED. This repository is not maintained, it is an old mirror of the inactive FreeImage project
C
34
star
12

hardwired

Hardwired - A 'NonCMS' for coders that applies the DRY and KISS principles to both content and code.
Ruby
25
star
13

imageflow-go

Go bindings for Imageflow -> https://github.com/imazen/imageflow
Go
17
star
14

resizer-web

Less
16
star
15

folioxml

Folio Flat File to XML/HTML/Lucene conversion framework
Java
12
star
16

slimresponse

Painless responsive images for .Net with Slimmage and ImageResizer
C#
11
star
17

resizer-images

This repository holds the ASP.NET project we use to deploy ImageResizer to z.zr.io
JavaScript
7
star
18

imageflow-ruby

These bindings are a work in progress; do not use
Ruby
5
star
19

repositext-idml-inspection

CSS
5
star
20

psdplugin-with-text

Fork of PsdPlugin with support for reading (and rendering) text layers
C#
4
star
21

reunion-sample

Starter sample for working with reunion
Ruby
4
star
22

repositext

Ruby
4
star
23

gd-libgd

Fork of LibGD for Windows & .NET support [deprecated]
C
3
star
24

libjpeg-turbo

DEPRECATED! Use libjpegturbo (without the dash) instead!
C
3
star
25

imageflow-web

Jekyll site for imageflow.io
HTML
3
star
26

imagetones

Tiny library to extract primary colors from a Bitmap.
C#
2
star
27

repositext-guide

Getting started with Repositext
Ruby
2
star
28

deprecated-gd-bindings-generator-old

Generates .NET bindings for libgd using CppSharp.
C#
2
star
29

dockerfiles_imageflow

DEPRECATED - do not use. These have been moved to imazen/imageflow/docker
Dockerfile
2
star
30

rust-openssl

Rust
1
star
31

repositext-web

repositext.org source
CSS
1
star
32

resizer-docs

Doxygen and Docu documentation for the ImageResizer project and its plugins
Graphviz (DOT)
1
star
33

ruby-vips-riapi

An experimental ruby wrapper for VIPS which may eventually be RIAPI compliant.
Ruby
1
star
34

suspension

Enables cross-format merging through token suspension.
Ruby
1
star
35

dhcpmanager

Better DHCP reservation management for Windows Server
JavaScript
1
star
36

gd-appveyor-helpers

PowerShell
1
star
37

hardwired-sample-minimal

An absurdly minimal example of a site running Hardwired
Ruby
1
star
38

collected

Collects documentation and API info from Imageflow*/ImageResizer* into a single markdown file for AI support use.
Python
1
star
39

paragon

Help create a demo for delivering unmanaged dependencies with NuGet
1
star
40

gd-dotnet-bindings-generator

Generates C# bindings for the LibGD library
C#
1
star