You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
***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.
6
-
***libimageflow** is for direct (in-process) use from *your* programming language. It has a simple [C-compatible ABI](https://s3-us-west-1.amazonaws.com/imageflow-nightlies/master/doc/imageflow/index.html) and [bindings](https://github.com/imazen/imageflow/tree/master/bindings).
7
-
***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](https://s3-us-west-1.amazonaws.com/imageflow-nightlies/master/doc/context_json_api.txt) 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).
10
8
11
-
libimageflow offers interactive job manipulation as well [like `/tell_decoder`, `/get_image_info`, and `/execute`](https://s3-us-west-1.amazonaws.com/imageflow-nightlies/master/doc/job_json_api.txt). Unless you are using memory buffers for I/O, it's better to use `/build`.
9
+
[Download](https://github.com/imazen/imageflow/releases) blazing fast and uniquely [safer](https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=imagemagick) tools for a modern image workflow.
12
10
13
-
[](https://github.com/imazen/imageflow/releases) or `docker run --rm imazen/imageflow_tool`
14
11
15
-
[We thank our backers on Kickstarter](https://www.kickstarter.com/projects/njones/imageflow-respect-the-pixels-a-secure-alt-to-image/posts/1616122) and [the many supporters of ImageResizer](https://imageresizing.net) for making this project a reality.
16
-
Email support@imageflow.io if you need an AGPLv3 exception for commercial use.
12
+
***imageflow_tool** is a command-line tool for experimenting, running batch jobs,
13
+
or when you want process isolation. Up to 17x faster than ImageMagick. Also produces smaller files at higher quality.
14
+
***imageflow_server** can run JSON jobs or manipulate images in-flight (e.g.`/bucket/img.jpg?w=200`) for direct use from
15
+
HTML. Source images can reside in blob storage, on another server, or on the filesystem.
16
+
***libimageflow** is for direct (in-process) use from *your* programming language. It has a simple
and [bindings](https://github.com/imazen/imageflow/tree/master/bindings).
19
+
20
+
**Note: We aren't labeling Imageflow as 'stable' until enough people have tested it. Please help us test and provide feedback!**
21
+
Also, please, *please*, **please**[send us 'challenging' images and tasks](https://github.com/imazen/imageflow/issues/98).
22
+
17
23
18
-
Also, please [send us 'challenging' images and tasks](https://github.com/imazen/imageflow/issues/98). We'd also appreciate it if you'd explore the JSON APIs and [review them and other topics where we are requesting feedback](https://github.com/imazen/imageflow/issues?q=is%3Aopen+is%3Aissue+label%3Arequesting-feedback). And – we need help with benchmarking on Windows.
24
+
These all offer the JSON [`/build` API](https://s3-us-west-1.amazonaws.com/imageflow-nightlies/master/doc/context_json_api.txt)
25
+
as well as the traditional `width=300&height=200&mode=crop&format=jpg` command string form. Each is available as a
26
+
[self-contained binary](https://github.com/imazen/imageflow/releases) for Windows, Ubuntu, and Mac. We also offer Docker images for Linux (where glibc and OpenSSL are required).
19
27
20
-
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](#flaws) for project status.**
28
+
libimageflow offers interactive job manipulation as well [like `/tell_decoder`, `/get_image_info`, and `/execute`](https://s3-us-west-1.amazonaws.com/imageflow-nightlies/master/doc/job_json_api.txt).
29
+
Unless you are using memory buffers for I/O, it's better to use `/build`.
30
+
31
+
[We thank our backers on Kickstarter](https://www.kickstarter.com/projects/njones/imageflow-respect-the-pixels-a-secure-alt-to-image/posts/1616122)
32
+
and [the many supporters of ImageResizer](https://imageresizing.net) for making this project a reality.
33
+
Email support@imageflow.io if you need an AGPLv3 exception for commercial use.
21
34
22
-
## Using imageflow_tool
35
+
36
+
## Start with imageflow_tool (recommended)
23
37
24
38
`imageflow_tool examples --generate` - creates an *examples* directory with JSON jobs and invocation scripts.
25
39
@@ -77,96 +91,146 @@ You'll want to mount various image source locations to prefixes. The `--mount` c
*C# - @samuelenglard has volunteered to create C# bindings for Imageflow. We're tracking [design here](https://github.com/imazen/imageflow/issues/67).
98
+
*Preview C# bindings can be found at https://github.com/imazen/imageflow-dotnet
85
99
* Ruby - Basic bindings can be found in [bindings/ruby/](https://github.com/imazen/imageflow/tree/master/bindings/ruby)
100
+
* C and C++ interface is stable - use [bindings/headers/imageflow_default.h](https://github.com/imazen/imageflow/blob/master/bindings/headers/imageflow_default.h) or one of the many alternate conventions provided with each release.
101
+
* Rust - Imageflow is written in Rust, so you can use the `imageflow_core` crate.
86
102
* Node - Not yet started. Want to help? [generate bindings from the header files](https://github.com/tjfontaine/node-ffi-generate)
87
-
* C and C++ - use [bindings/headers/imageflow_default.h](https://github.com/imazen/imageflow/blob/master/bindings/headers/imageflow_default.h) or one of the many alternate conventions provided with each release.
88
-
* Rust - Imageflow is written in Rust. Use the `imageflow_core` crate, but be warned that this interface will evolve more rapidly than the FFI `imageflow` crate.
89
103
* other languages - Use an [FFI](https://en.wikipedia.org/wiki/Foreign_function_interface) binding-generation tool for your language, and feed it whichever [header file it likes best](https://github.com/imazen/imageflow/tree/master/bindings/headers).
90
104
91
-
Official Ruby and Node bindings will be released by August 2017.
105
+
You also may find that `imageflow_tool` is quite fast enough for your needs.
92
106
107
+
### Crates within this project
93
108
94
-
# How to build Imageflow from source
109
+
* imageflow_abi - The stable API of libimageflow/imageflow.dll.
110
+
Headers for libimageflow are located in `bindings/headers`
111
+
* imageflow_tool - The command-line tool
112
+
* imageflow_server - The HTTP server
113
+
* c_components - A rust crate containing C source
114
+
* c_components/tests - Tests for the C components
115
+
* imageflow_types - Shared types used by most crates, with JSON serialization
116
+
* imageflow_helpers - Common helper functions and utilities
117
+
* imageflow_riapi - RIAPI and ImageResizer4 compatibility parsing/layout
118
+
* imageflow_core - The main library and execution engine
95
119
96
-
We're assuming you've cloned already.
97
120
98
-
```bash
99
-
git clone git@github.com:imazen/imageflow.git
100
-
cd imageflow
101
-
```
121
+
### Known flaws and missing features (as of July 2017)
102
122
103
-
##Docker (linux/macOS/WinUbuntu)
123
+
#### Flaws
104
124
105
-
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.
125
+
-[ ] imageflow_server doesn't expose the JSON API yet.
126
+
-[ ] No fuzz testing or third-party auditing yet.
106
127
107
-
```bash
108
-
./build_via_docker.sh debug
109
-
```
128
+
#### Missing features
110
129
130
+
-[ ] Animated GIF write support (reading individual frames is supported)
131
+
-[ ] Some advanced rendering features: Whitespace detection/cropping, watermarking, blurring.
132
+
-[ ] Automatic encoder selection and tuning.
111
133
112
-
##Linux (native)
134
+
#### Delayed features
113
135
114
-
We need a few packages in order to build the C dependencies. You probably have most of these already.
136
+
-[ ] Job cost prediction (delayed - no interest from community)
137
+
-[ ] Node bindings (delayed - no interest from community)
115
138
116
-
* build-essential, nasm, pkg-config
117
-
* wget, curl, git
118
-
* libpng, libssl, ca-certificates
119
139
120
-
## For Ubuntu 14.04 and 16.04:
140
+
#Building from Source without Docker
121
141
122
-
```bash
123
-
sudo apt-get install --no-install-recommends \
124
-
build-essential nasm pkg-config \
125
-
wget curl git ca-certificates \
126
-
libpng-dev libssl-dev
127
-
```
142
+
You'll need more than just Rust to compile Imageflow, as it has a couple C dependencies.
128
143
129
-
After installing the above, you'll need dssim, and Rust Nightly.
144
+
1.**Install platform-specific prerequisites (find the right section below).**
145
+
2. Run `cargo install dssim`
146
+
3. Clone and cd into this repository
147
+
E.g., `git clone git@github.com:imazen/imageflow.git && cd imageflow`)
130
148
131
-
```bash
132
-
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly-2018-04-04
133
-
./ci/nixtools/install_dssim.sh
134
-
./build.sh
135
-
```
149
+
If you are using `bash` on any platform, you should be able to use `build.sh`
2. Run from a bash session (Windows WSL, macOS, or linux)
174
+
3.```bash
175
+
git clone git@github.com:imazen/imageflow.git
176
+
cd imageflow
177
+
./build_via_docker.sh debug
178
+
```
179
+
180
+
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.
181
+
182
+
The [official Dockerfiles](https://github.com/imazen/dockerfiles_imageflow) are also a great place to get more detailed environment setup steps, as we don't list steps for setting up:
139
183
* Valgrind (common versions break openssl; you may need to build from source)
140
184
* Code coverage
141
185
* Bindings.
142
186
143
-
Please consult the [official Dockerfiles](https://github.com/imazen/dockerfiles_imageflow) for these.
144
-
145
-
## OS X (native)
187
+
## Linux Pre-requisites
146
188
147
-
You'll need a bit less on OS X, although this may not be comprehensive:
189
+
(tested on Ubuntu 14.04, 16.04, and 18.04.)
148
190
149
191
```bash
150
-
brew install nasm libpng pkg-config wget
151
-
./ci/nixtools/install_dssim.sh
152
-
./build.sh
192
+
#Install Rust Nightly by running
193
+
`curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly-2018-05-15`
3. Install [NASM 64-bit](http://www.nasm.us/pub/nasm/releasebuilds/2.12.02/win64/nasm-2.12.02-installer-x64.exe) Installer must be `Run as Administrator` - it will not prompt.
161
-
4. Install [Rust 64-bit](https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe). Install toolchain `nightly-2018-04-04` and set it as default. For the moment, 32-bit builds also require [a 32-bit Rust](https://static.rust-lang.org/rustup/dist/i686-pc-windows-msvc/rustup-init.exe).
162
206
163
-
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.
207
+
## Windows WSL (Ubuntu Bionic Subsystem) Pre-requisites
164
208
165
-
1. 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).
166
-
4.`cd ..\..` back to the root and run `win_build_c.bat` again.
167
-
5. Run `win_build_rust.bat` to compile the Rust components
209
+
1. Install [Ubuntu 18.04 from the Windows Store](https://www.microsoft.com/store/productId/9N9TNGVNDL3Q)
210
+
2. Run Ubuntu 18.04 and create your username/password
211
+
3.`sudo apt-get update` to update available packages.
212
+
4. Install Rust Nightly by running
213
+
`curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain nightly-2018-05-15`
1. Install Visual Studio 2017 Build Tools ([separately](https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15) or as a VS component)
3.`Run As Administrator` the [NASM 64-bit](http://www.nasm.us/pub/nasm/releasebuilds/2.12.02/win64/nasm-2.12.02-installer-x64.exe) installer - it will not prompt.
227
+
4. Install [Rust 64-bit](https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe) if you want 64-bit Imageflow or [Rust 32-bit](https://static.rust-lang.org/rustup/dist/i686-pc-windows-msvc/rustup-init.exe) if you don't.
228
+
Install toolchain `nightly-2018-05-15` as the default, and confirm adding it to `PATH`.
229
+
5. Open the command line and switch to this repository's root directory
230
+
5. Edit `ci/wintools/SETUP_PATH.bat` to ensure that rust/cargo, nasm, git, and Git/mingw64/bin are all in `%PATH%`.
231
+
7. Run `win_enter_env.bat` to start a sub-shell (edit it if you want a 32-bit build)
232
+
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.
233
+
170
234
## How does one learn image processing for the web?
171
235
172
236
First, [read High Performance Images](http://shop.oreilly.com/product/0636920039730.do) for context.
@@ -184,37 +248,3 @@ I would start by reading [Principles of Digital Image Processing: Core Algorithm
184
248
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](https://github.com/imazen/Graphics-vNext/blob/master/aware.md).
185
249
186
250
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.
187
-
188
-
### Source organization
189
-
190
-
Rust crates
191
-
192
-
* imageflow_types - Shared types, with JSON serialization
193
-
* imageflow_helpers - Common helper functions and utilities
194
-
* imageflow_riapi - RIAPI and ImageResizer4 compatibility parsing/layout
195
-
* imageflow_core - The main library
196
-
* imageflow_abi - The C-Compatible API - exposes functionality from imageflow_core
197
-
* imageflow_tool
198
-
* imageflow_server
199
-
200
-
C source is located in ./c_components/lib, and ./c_components/tests
201
-
202
-
Headers for libimageflow.dll are located in `bindings/headers`
203
-
204
-
### Known flaws and missing features (as of July 2017)
205
-
206
-
#### Flaws
207
-
208
-
-[ ] imageflow_server doesn't expose the JSON API yet.
209
-
-[ ] No fuzz testing or third-party auditing yet.
210
-
211
-
#### Missing features
212
-
213
-
-[ ] Animated GIF write support (reading individual frames is supported)
214
-
-[ ] Some advanced rendering features: Whitespace detection/cropping, watermarking, blurring.
215
-
-[ ] Automatic encoder selection and tuning.
216
-
217
-
#### Delayed features
218
-
219
-
-[ ] Job cost prediction (delayed - no interest from community)
220
-
-[ ] Node bindings (delayed - no interest from community)
0 commit comments