2012-06-29 13:20:50 +02:00
# libvips : an image processing library
2007-08-29 18:23:50 +02:00
2018-09-21 18:05:47 +02:00
[![Build Status ](https://travis-ci.org/libvips/libvips.svg?branch=master )](https://travis-ci.org/libvips/libvips)
2019-09-19 07:05:42 +02:00
[![Fuzzing Status ](https://oss-fuzz-build-logs.storage.googleapis.com/badges/libvips.svg )](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened& can=2& q=proj:libvips)
2019-10-18 02:40:58 +02:00
[![Financial Contributors on Open Collective ](https://opencollective.com/libvips/all/badge.svg?label=financial+contributors )](https://opencollective.com/libvips) [![Coverity Status ](https://scan.coverity.com/projects/6503/badge.svg )](https://scan.coverity.com/projects/jcupitt-libvips)
2015-09-30 12:37:42 +02:00
2018-08-17 18:52:45 +02:00
libvips is a [demand-driven, horizontally
2018-09-21 18:05:47 +02:00
threaded](https://github.com/libvips/libvips/wiki/Why-is-libvips-quick)
2018-08-17 18:52:45 +02:00
image processing library. Compared to similar
libraries, [libvips runs quickly and uses little
2018-09-21 18:05:47 +02:00
memory](https://github.com/libvips/libvips/wiki/Speed-and-memory-use).
2018-08-17 18:52:45 +02:00
libvips is licensed under the [LGPL
2.1+](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html).
2018-09-25 11:43:37 +02:00
It has around [300
operations](http://libvips.github.io/libvips/API/current/func-list.html)
covering arithmetic, histograms, convolution, morphological
operations, frequency filtering, colour, resampling,
statistics and others. It supports a large range of [numeric
2019-02-10 06:31:33 +01:00
types](http://libvips.github.io/libvips/API/current/VipsImage.html#VipsBandFormat),
2018-08-17 18:52:45 +02:00
from 8-bit int to 128-bit complex. Images can have any number of bands.
2019-06-15 14:14:26 +02:00
It supports a good range of image formats, including JPEG, TIFF, PNG,
WebP, HEIC, FITS, Matlab, OpenEXR, PDF, SVG, HDR, PPM / PGM / PFM, CSV,
GIF, Analyze, NIfTI, DeepZoom, and OpenSlide. It can also load images via
ImageMagick or GraphicsMagick, letting it work with formats like DICOM.
2018-09-25 11:43:37 +02:00
It comes with bindings for
[C ](http://libvips.github.io/libvips/API/current/using-from-c.html ),
[C++ ](http://libvips.github.io/libvips/API/current/using-from-cpp.html ),
and the
[command-line ](http://libvips.github.io/libvips/API/current/using-cli.html ).
Full bindings are available for [Ruby ](https://rubygems.org/gems/ruby-vips ),
2018-08-17 18:52:45 +02:00
[Python ](https://pypi.python.org/pypi/pyvips ),
2018-09-21 18:05:47 +02:00
[PHP ](https://github.com/libvips/php-vips ),
2019-02-10 06:31:33 +01:00
[C# / .NET ](https://www.nuget.org/packages/NetVips ),
2018-08-17 18:52:45 +02:00
[Go ](https://github.com/davidbyttow/govips ), and
2018-09-21 18:05:47 +02:00
[Lua ](https://github.com/libvips/lua-vips ). libvips
2018-09-25 11:43:37 +02:00
is used as an image processing engine by [sharp
(on node.js)](https://www.npmjs.org/package/sharp),
[bimg ](https://github.com/h2non/bimg ), [sharp
for Go](https://github.com/DAddYE/vips), [Ruby on
Rails](http://edgeguides.rubyonrails.org/active_storage_overview.html),
2018-08-17 18:52:45 +02:00
[carrierwave-vips ](https://github.com/eltiare/carrierwave-vips ),
[mediawiki ](http://www.mediawiki.org/wiki/Extension:VipsScaler ),
[PhotoFlow ](https://github.com/aferrero2707/PhotoFlow ) and others.
2018-09-21 18:05:47 +02:00
The official libvips GUI is [nip2 ](https://github.com/libvips/nip2 ),
2018-08-17 18:52:45 +02:00
a strange combination of a spreadsheet and an photo editor.
2007-08-29 18:23:50 +02:00
2019-06-15 14:21:43 +02:00
# Install
2008-03-26 17:56:51 +01:00
2019-07-18 09:43:41 +02:00
There are packages for most Unix-like operating systems, including
macOS. Check your package manager.
2019-06-15 14:21:43 +02:00
There are binaries for Windows in
[releases ](https://github.com/libvips/libvips/releases ).
The [libvips website ](https://libvips.github.io/libvips ) has [detailed
install notes](https://libvips.github.io/libvips/install.html).
2007-08-29 18:23:50 +02:00
2019-06-15 14:21:43 +02:00
# Building libvips from a source tarball
2016-04-07 10:37:16 +02:00
2019-06-15 14:21:43 +02:00
We keep pre-baked tarballs in
[releases ](https://github.com/libvips/libvips/releases ).
2016-04-07 10:37:16 +02:00
Untar, then in the libvips directory you should just be able to do:
2007-08-29 18:23:50 +02:00
2019-08-15 03:37:31 +02:00
./configure
2015-05-05 14:50:43 +02:00
2018-07-07 17:22:17 +02:00
Check the summary at the end of `configure` carefully. libvips must have
`build-essential` , `pkg-config` , `glib2.0-dev` , `libexpat1-dev` .
2015-05-05 14:50:43 +02:00
2018-07-07 17:22:17 +02:00
You'll need the dev packages for the file format support you want. For basic
jpeg and tiff support, you'll need `libtiff5-dev` , `libjpeg-turbo8-dev` ,
and `libgsf-1-dev` . See the **Dependencies** section below for a full list
of the things that libvips can be configured to use.
2015-05-05 14:50:43 +02:00
Once `configure` is looking OK, compile and install with the usual:
2019-08-15 03:37:31 +02:00
make
sudo make install
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
By default this will install files to `/usr/local` .
2007-08-29 18:23:50 +02:00
2018-07-07 17:22:17 +02:00
# Testing
2019-08-15 03:37:31 +02:00
Run the test suite with:
2018-07-07 17:22:17 +02:00
2019-08-15 03:37:31 +02:00
make check
2018-07-07 18:07:35 +02:00
Run a specific test with:
2019-08-15 03:37:31 +02:00
pytest --verbose
pytest test/test-suite/test_foreign.py -k test_tiff
2018-07-07 17:22:17 +02:00
2014-11-26 12:07:10 +01:00
# Building libvips from git
2009-08-27 15:07:58 +02:00
2019-06-15 14:21:43 +02:00
Clone the latest sources with:
2009-08-27 15:07:58 +02:00
2019-08-15 03:37:31 +02:00
git clone git://github.com/libvips/libvips.git
2009-08-27 15:07:58 +02:00
2019-06-15 14:21:43 +02:00
Building from git needs more packages -- you'll need at least `gtk-doc`
2015-05-05 14:50:43 +02:00
and `gobject-introspection` , see the dependencies section below. For example:
2009-08-27 15:07:58 +02:00
2019-08-15 03:37:31 +02:00
brew install gtk-doc
2009-08-27 15:07:58 +02:00
2014-11-26 12:07:10 +01:00
Then build the build system with:
2014-11-26 00:44:58 +01:00
2019-08-15 03:37:31 +02:00
./autogen.sh --prefix=/home/john/vips
2014-11-26 12:07:10 +01:00
Debug build:
2019-08-15 03:37:31 +02:00
CFLAGS="-g -Wall" CXXFLAGS="-g -Wall" \
./configure --prefix=/home/john/vips --enable-debug
make
make install
2014-11-26 00:44:58 +01:00
2019-08-15 03:37:31 +02:00
Leak check. Use the suppressions file `supp/valgrind.supp` .
2013-07-15 23:01:00 +02:00
2019-08-15 03:37:31 +02:00
export G_DEBUG=gc-friendly
valgrind --suppressions=vips-x.y.z/supp/valgrind.supp \
--leak-check=yes \
vips ... > vips-vg.log 2>& 1
2013-07-15 23:01:00 +02:00
2016-11-18 12:57:01 +01:00
Memory error debug:
2019-08-15 03:37:31 +02:00
valgrind --vgdb=yes --vgdb-error=0 vips ...
2016-11-18 12:57:01 +01:00
2014-01-14 13:21:21 +01:00
valgrind threading check:
2019-08-15 03:37:31 +02:00
valgrind --tool=helgrind vips ... > vips-vg.log 2>& 1
2014-01-14 13:21:21 +01:00
2013-11-22 11:12:54 +01:00
Clang build:
2019-08-15 03:37:31 +02:00
CC=clang CXX=clang++ ./configure --prefix=/home/john/vips
2013-11-22 11:12:54 +01:00
2013-11-22 12:27:29 +01:00
Clang static analysis:
2019-08-15 03:37:31 +02:00
scan-build ./configure --disable-introspection --disable-debug
scan-build -o scan -v make
scan-view scan/2013-11-22-2
2013-11-22 12:27:29 +01:00
2013-11-22 11:12:54 +01:00
Clang dynamic analysis:
2019-08-15 03:37:31 +02:00
FLAGS="-g -O1 -fno-omit-frame-pointer"
CC=clang CXX=clang++ LD=clang \
CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" LDFLAGS=-fsanitize=address \
./configure --prefix=/home/john/vips
2018-07-07 18:07:35 +02:00
2019-08-15 03:37:31 +02:00
FLAGS="-O1 -g -fsanitize=thread"
FLAGS="$FLAGS -fPIC"
FLAGS="$FLAGS -fno-omit-frame-pointer -fno-optimize-sibling-calls"
CC=clang CXX=clang++ LD=clang \
2018-07-07 18:07:35 +02:00
CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" \
LDFLAGS="-fsanitize=thread -fPIC" \
./configure --prefix=/home/john/vips \
--without-magick \
--disable-introspection
2019-08-15 03:37:31 +02:00
G_DEBUG=gc-friendly vips copy ~/pics/k2.jpg x.jpg >& log
2013-11-22 11:12:54 +01:00
2013-12-05 15:40:42 +01:00
Build with the GCC auto-vectorizer and diagnostics (or just -O3):
2013-12-03 13:39:13 +01:00
2019-08-15 03:37:31 +02:00
FLAGS="-O2 -march=native -ffast-math"
FLAGS="$FLAGS -ftree-vectorize -fdump-tree-vect-details"
CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" \
2018-07-07 18:07:35 +02:00
./configure --prefix=/home/john/vips
2013-12-03 13:39:13 +01:00
2012-06-29 13:20:50 +02:00
# Dependencies
2007-08-29 18:23:50 +02:00
2019-08-15 03:37:31 +02:00
libvips has to have `glib2.0-dev` and `libexpat1-dev` . Other dependencies
are optional, see below.
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
# Optional dependencies
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
If suitable versions are found, libvips will add support for the following
2012-06-29 13:36:56 +02:00
libraries automatically. See `./configure --help` for a set of flags to
control library detection. Packages are generally found with `pkg-config` ,
2011-02-14 12:34:13 +01:00
so make sure that is working.
2007-08-29 18:23:50 +02:00
2019-08-15 03:37:31 +02:00
Libraries like giflib and nifti do not use `pkg-config` so libvips will also
look for them in the default path and in `$prefix` . If you have installed
your own versions of these libraries in a different location, libvips will
not see them. Use switches to libvips configure like:
2007-08-29 18:23:50 +02:00
2018-07-07 18:07:35 +02:00
./configure --prefix=/Users/john/vips \
2019-08-15 03:37:31 +02:00
--with-giflib-includes=/opt/local/include \
--with-giflib-libraries=/opt/local/lib
2008-10-11 23:29:16 +02:00
or perhaps:
2018-07-07 18:07:35 +02:00
CFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \
2019-04-27 12:41:26 +02:00
CXXFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \
./configure --prefix=/Users/john/vips
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
### libjpeg
2012-06-29 13:20:50 +02:00
2015-07-10 13:44:02 +02:00
The IJG JPEG library. Use the `-turbo` version if you can.
2012-06-29 13:20:50 +02:00
2015-07-10 13:44:02 +02:00
### libexif
2012-06-29 13:20:50 +02:00
2012-06-29 13:36:56 +02:00
If available, libvips adds support for EXIF metadata in JPEG files.
2012-06-29 13:20:50 +02:00
2016-03-08 10:00:57 +01:00
### giflib
The standard gif loader. If this is not present, vips will try to load gifs
via imagemagick instead.
### librsvg
The usual SVG loader. If this is not present, vips will try to load SVGs
via imagemagick instead.
2018-04-07 18:36:52 +02:00
### PDFium
If present, libvips will attempt to load PDFs via PDFium. This library must be
2018-10-06 05:31:38 +02:00
packaged by https://github.com/jcupitt/docker-builds/tree/master/pdfium
2018-04-07 18:36:52 +02:00
If PDFium is not detected, libvips will look for poppler-glib instead.
2019-04-27 12:41:26 +02:00
### poppler-glib
2016-03-08 10:00:57 +01:00
2019-04-27 12:41:26 +02:00
The Poppler PDF renderer, with a glib API. If this is not present, vips
will try to load PDFs via imagemagick.
2016-03-08 10:00:57 +01:00
2015-07-10 13:44:02 +02:00
### libgsf-1
2014-05-09 14:13:18 +02:00
2015-07-10 13:44:02 +02:00
If available, libvips adds support for creating image pyramids with `dzsave` .
2014-05-09 14:13:18 +02:00
2015-07-10 13:44:02 +02:00
### libtiff
2012-06-29 13:20:50 +02:00
The TIFF library. It needs to be built with support for JPEG and
ZIP compression. 3.4b037 and later are known to be OK.
2015-07-10 13:44:02 +02:00
### fftw3
2012-06-29 13:20:50 +02:00
2015-07-10 13:44:02 +02:00
If libvips finds this library, it uses it for fourier transforms.
2012-06-29 13:20:50 +02:00
2019-04-27 12:41:26 +02:00
### lcms2
2012-06-29 13:20:50 +02:00
2015-07-10 13:44:02 +02:00
If present, `vips_icc_import()` , `vips_icc_export()` and `vips_icc_transform()`
2019-04-27 12:41:26 +02:00
are available for transforming images with ICC profiles.
2012-06-29 13:20:50 +02:00
2015-07-10 13:44:02 +02:00
### libpng
2012-06-29 13:20:50 +02:00
2012-06-29 13:36:56 +02:00
If present, libvips can load and save png files.
2007-08-29 18:23:50 +02:00
2018-08-07 16:07:38 +02:00
### libimagequant
If present, libvips can write 8-bit palette-ised PNGs.
2015-07-10 13:44:02 +02:00
### ImageMagick, or optionally GraphicsMagick
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
If available, libvips adds support for loading all libMagick-supported
image file types. Use `--with-magickpackage=GraphicsMagick` to build against
graphicsmagick instead.
2007-08-29 18:23:50 +02:00
2016-05-05 10:14:58 +02:00
Imagemagick 6.9+ needs to have been built with `--with-modules` . Most packaged
2018-06-11 13:23:18 +02:00
IMs are, I think.
2016-05-05 10:14:58 +02:00
2016-05-09 15:06:44 +02:00
If you are going to be using libvips with untrusted images, perhaps in a
2019-04-27 12:41:26 +02:00
web server, for example, you should consider the security implications of
enabling a package with such a large attack surface.
2016-05-09 15:06:44 +02:00
2015-07-10 13:44:02 +02:00
### pangoft2
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
If available, libvips adds support for text rendering. You need the
package pangoft2 in `pkg-config --list-all` .
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
### orc-0.4
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
If available, vips will accelerate some operations with this run-time
compiler.
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
### matio
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
If available, vips can load images from Matlab save files.
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
### cfitsio
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
If available, vips can load FITS images.
2007-08-29 18:23:50 +02:00
2015-07-10 13:44:02 +02:00
### libwebp
2015-01-26 15:58:49 +01:00
If available, vips can load and save WebP images.
2018-08-07 16:07:38 +02:00
### libniftiio
If available, vips can load and save NIFTI images.
2015-07-10 13:44:02 +02:00
### OpenEXR
2011-01-06 15:18:00 +01:00
2012-06-29 13:36:56 +02:00
If available, libvips will directly read (but not write, sadly)
OpenEXR images.
2011-01-06 15:18:00 +01:00
2015-07-10 13:44:02 +02:00
### OpenSlide
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
If available, libvips can load OpenSlide-supported virtual slide
2014-01-25 08:31:20 +01:00
files: Aperio, Hamamatsu, Leica, MIRAX, Sakura, Trestle, and Ventana.
2007-08-29 18:23:50 +02:00
2019-04-27 12:41:26 +02:00
### libheif
If available, libvips can load and save HEIC images.
2012-06-29 13:20:50 +02:00
# Disclaimer
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
No guarantees of performance accompany this software, nor is any
2007-08-29 18:23:50 +02:00
responsibility assumed on the part of the authors. Please read the licence
agreement.
2019-10-18 02:40:58 +02:00
## Contributors
### Code Contributors
This project exists thanks to all the people who contribute. [[Contribute ](CONTRIBUTING.md )].
< a href = "https://github.com/libvips/libvips/graphs/contributors" > < img src = "https://opencollective.com/libvips/contributors.svg?width=890&button=false" / > < / a >
### Financial Contributors
Become a financial contributor and help us sustain our community. [[Contribute ](https://opencollective.com/libvips/contribute )]
#### Individuals
< a href = "https://opencollective.com/libvips" > < img src = "https://opencollective.com/libvips/individuals.svg?width=890" > < / a >
#### Organizations
Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute ](https://opencollective.com/libvips/contribute )]
< a href = "https://opencollective.com/libvips/organization/0/website" > < img src = "https://opencollective.com/libvips/organization/0/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/1/website" > < img src = "https://opencollective.com/libvips/organization/1/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/2/website" > < img src = "https://opencollective.com/libvips/organization/2/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/3/website" > < img src = "https://opencollective.com/libvips/organization/3/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/4/website" > < img src = "https://opencollective.com/libvips/organization/4/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/5/website" > < img src = "https://opencollective.com/libvips/organization/5/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/6/website" > < img src = "https://opencollective.com/libvips/organization/6/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/7/website" > < img src = "https://opencollective.com/libvips/organization/7/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/8/website" > < img src = "https://opencollective.com/libvips/organization/8/avatar.svg" > < / a >
< a href = "https://opencollective.com/libvips/organization/9/website" > < img src = "https://opencollective.com/libvips/organization/9/avatar.svg" > < / a >