- imageflow_server can run jobs or 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. - libimageflow is for direct (in-process) use from your programming language. It has a simple C-compatible ABI and bindings.
- imageflow_tool is a command-line tool for experimenting, running batch jobs, or when you want process isolation. Up to 17x faster than ImageMagick.
These all offer the JSON /build
API as well as the traditional width=300&height=200&mode=crop&format=jpg
command string form. Each is available as a self-contained binary for Windows and Mac. We offer Docker images for Linux (where glibc and OpenSSL are required).
libimageflow offers interactive job manipulation as well like /tell_decoder
, /get_image_info
, and /execute
. Unless you are using memory buffers for I/O, it's better to use /build
.
or
docker run --rm imazen/imageflow_tool
We thank our backers on Kickstarter and the many supporters of ImageResizer for making this project a reality. Email [email protected] if you need an AGPLv3 exception for commercial use.
Also, please send us 'challenging' images and tasks. We'd also appreciate it if you'd explore the JSON APIs and review them and other topics where we are requesting feedback. And โ we need help with benchmarking on Windows.
If we enough people beta-test Imageflow and provide feedback, we aim to publish a stable 1.0 release in August 2017 (along with Ruby and Node bindings). See flaws and missing features for project status.
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 v0.1/ir4 --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 mutiple sizes of an image from an example job file:
imageflow_tool v0.1/build --json examples/export_4_sizes/export_4_sizes.json
--in http://s3-us-west-2.amazonaws.com/imageflow-resources/test_inputs/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 v0.1/build
and v0.1/ir4
. Please sumbit bug reports; we try to make it easy.
imageflow_server start --demo
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" />
You'll want to mount varous 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.
--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"
- C# - @samuelenglard has volunteered to create C# bindings for Imageflow. We're tracking design here.
- Ruby - Basic bindings can be found in bindings/ruby/
- Node - Not yet started. Want to help? generate bindings from the header files
- C and C++ - use bindings/headers/imageflow_default.h or one of the many alternate conventions provided with each release.
- Rust - Imageflow is written in Rust. Use the
imageflow_core
crate, but be warned that this interface will evolve more rapidly than the FFIimageflow
crate. - other languages - Use an FFI binding-generation tool for your language, and feed it whichever header file it likes best.
Official Ruby and Node bindings will be released by August 2017.
We're assuming you've cloned already.
git clone [email protected]:imazen/imageflow.git
cd imageflow
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.
./build_via_docker.sh debug
We need a few packages in order to build the C dependencies. You probably have most of these already.
- build-essential, nasm, pkg-config
- wget, curl, git
- libpng, libssl, ca-certificates
sudo apt-get install --no-install-recommends \
build-essential nasm pkg-config \
wget curl git ca-certificates \
libpng-dev libssl-dev
After installing the above, you'll need dssim, and Rust Nightly.
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly-2017-08-01
./ci/nixtools/install_dssim.sh
./build.sh
We aren't listing dependencies needed for
- Valgrind (common versions break openssl; you may need to build from source)
- Code coverage
- Bindings.
Please consult the official Dockerfiles for these.
You'll need a bit less on OS X, although this may not be comprehensive:
brew install nasm libpng pkg-config wget
./ci/nixtools/install_dssim.sh
./build.sh
- Visual Studio 2015 (for the C++ build tools)
- Install Git 64-bit.
- Install NASM 64-bit Installer must be
Run as Administrator
- it will not prompt. - Install Rust 64-bit. Install toolchain
nightly-2017-06-08
and set it as default. For the moment, 32-bit builds also require a 32-bit Rust.
You need all of these to be in %PATH%. Edit ci/wintools/SETUP_PATH.bat
as appropriate to ensure that rust/cargo, nasm, git, and Git/mingw64/bin are all available.
- Run
win_enter_env.bat
to start a sub-shell with VS tools loaded and a proper PATH. Edit the file per its comments to target a 32-bit build (you may want a separate imageflow folder for each target). cd ..\..
back to the root and runwin_build_c.bat
again.- Run
win_build_rust.bat
to compile the Rust components
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".
- Digital Image Warping
- Computer Graphics: Principles and Practice in C (2nd Edition)
- Principles of Digital Image Processing: Fundamental Techniques
- Principles of Digital Image Processing: Core Algorithms
- Principles of Digital Image Processing: Advanced Methods
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.
Rust crates
- imageflow_types - Shared types, with JSON serialization
- imageflow_helpers - Common helper functions and utilities
- imageflow_riapi - RIAPI and ImageResizer4 compatibility parsing/layout
- imageflow_core - The main library
- imageflow_abi - The C-Compatible API - exposes functionality from imageflow_core
- imageflow_tool
- imageflow_server
C source is located in ./c_components/lib, and ./c_components/tests
Headers for libimageflow.dll are located in bindings/headers
- imageflow_server doesn't expose the JSON API yet.
- No fuzz testing or third-party auditing yet.
- Animated GIF write support (reading individual frames is supported)
- Some advanced rendering features: Whitespace detection/cropping, watermarking, blurring.
- Automatic encoder selection and tuning.
- Job cost prediction (delayed - no interest from community)
- Node bindings (delayed - no interest from community)