libvips/README.md

235 lines
6.7 KiB
Markdown
Raw Normal View History

2012-06-29 13:20:50 +02:00
# libvips : an image processing library
2007-08-29 18:23:50 +02:00
2014-05-19 15:53:47 +02:00
[![Build Status](https://secure.travis-ci.org/jcupitt/libvips.png)](http://travis-ci.org/jcupitt/libvips)
2015-01-26 15:58:49 +01:00
libvips is a 2D image processing library. Compared to
similar libraries, [libvips runs quickly and uses little
2014-03-20 13:22:04 +01:00
memory](http://www.vips.ecs.soton.ac.uk/index.php?title=Speed_and_Memory_Use).
2015-01-26 15:58:49 +01:00
livips is licensed under the LGPL 2.1+.
2014-03-20 13:22:04 +01:00
2014-03-20 15:52:06 +01:00
It has around 300 operations covering arithmetic, histograms, convolutions,
2014-03-20 13:22:04 +01:00
morphological operations, frequency filtering, colour, resampling, statistics
and others. It supports a large range of numeric formats, from 8-bit int to
128-bit complex. It supports a good range of image formats, including
2015-01-26 15:58:49 +01:00
JPEG, TIFF, PNG, WebP, FITS, Matlab, OpenEXR, DeepZoom, and OpenSlide.
It can also load images via ImageMagick or GraphicsMagick.
2014-03-20 13:22:04 +01:00
It has APIs for C and C++ and comes with a Python
binding and a command-line interface. Bindings are
2015-01-26 15:58:49 +01:00
available for Ruby, JavaScript and others. There is full
[documentation](http://www.vips.ecs.soton.ac.uk/supported/current/doc/html/libvips/index.html).
2014-03-20 13:22:04 +01:00
There's a GUI as well, see the [VIPS website](http://www.vips.ecs.soton.ac.uk).
2007-08-29 18:23:50 +02:00
2012-06-29 13:36:56 +02:00
There are packages for most unix-like operating systems and binaries for
2011-01-06 15:18:00 +01:00
Windows and OS X.
2008-03-26 17:56:51 +01:00
2012-06-29 13:20:50 +02:00
# Building libvips from source
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
In the libvips directory you should just be able to do:
2007-08-29 18:23:50 +02:00
2009-08-27 15:07:58 +02:00
$ ./configure
$ 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
2012-06-29 13:20:50 +02:00
See the Dependencies section below for a list of the things that
libvips needs in order to be able to build.
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
We have detailed guides on the wiki for [building on
Windows](http://www.vips.ecs.soton.ac.uk/index.php?title=Build_on_windows)
and [building on OS
X](http://www.vips.ecs.soton.ac.uk/index.php?title=Build_on_OS_X).
2007-08-29 18:23:50 +02:00
2014-11-26 12:07:10 +01:00
# Building libvips from git
2009-08-27 15:07:58 +02:00
Checkout the latest sources with:
2012-06-29 13:36:56 +02:00
$ git clone git://github.com/jcupitt/libvips.git
2009-08-27 15:07:58 +02:00
2014-11-26 12:07:10 +01:00
Building from git needs more packages. You'll need at least swig and gtk-doc,
see the dependencies section below. For example:
2009-08-27 15:07:58 +02:00
2014-11-26 12:07:10 +01:00
$ brew install gtk-doc swig
2009-08-27 15:07:58 +02:00
2014-11-26 12:07:10 +01:00
Then build the build system with:
$ ./bootstrap.sh
2014-11-26 12:07:10 +01:00
Debug build:
$ CFLAGS="-g -Wall" CXXFLAGS="-g -Wall" \
./configure --prefix=/home/john/vips
$ make
$ make install
2013-07-15 23:01:00 +02:00
Leak check:
$ export G_DEBUG=gc-friendly
2013-07-15 23:01:00 +02:00
$ export G_SLICE=always-malloc
2014-01-14 13:21:21 +01:00
$ valgrind --suppressions=libvips.supp \
2013-07-15 23:01:00 +02:00
--leak-check=yes \
vips ... > vips-vg.log 2>&1
2014-01-14 13:21:21 +01:00
valgrind threading check:
$ valgrind --tool=helgrind vips ... > vips-vg.log 2>&1
2013-11-22 11:12:54 +01:00
Clang build:
$ CC=clang CXX=clang++ ./configure --prefix=/home/john/vips
2013-11-22 12:27:29 +01:00
Clang static analysis:
$ scan-build ./configure --disable-introspection
2013-11-22 12:27:29 +01:00
$ 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:
$ FLAGS="-O1 -g -fsanitize=address"
$ FLAGS="$FLAGS -fno-omit-frame-pointer -fno-optimize-sibling-calls"
2013-11-22 11:12:54 +01:00
$ CC=clang CXX=clang++ LD=clang \
CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" LDFLAGS=-fsanitize=address \
2013-11-22 11:12:54 +01:00
./configure --prefix=/home/john/vips --disable-introspection
$ FLAGS="-O1 -g -fsanitize=thread"
$ FLAGS="$FLAGS -fPIC -pie"
$ FLAGS="$FLAGS -fno-omit-frame-pointer -fno-optimize-sibling-calls"
2013-11-22 11:12:54 +01:00
$ CC=clang CXX=clang++ LD=clang \
CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" \
2013-11-22 15:50:40 +01:00
LDFLAGS="-fsanitize=thread -fPIC -pie" \
2013-11-22 11:12:54 +01:00
./configure --prefix=/home/john/vips --disable-introspection
2013-12-05 15:40:42 +01:00
Build with the GCC auto-vectorizer and diagnostics (or just -O3):
$ FLAGS="-O2 -msse4.2 -ffast-math"
$ FLAGS="$FLAGS -ftree-vectorize -fdump-tree-vect-details"
$ CFLAGS="$FLAGS" CXXFLAGS="$FLAGS" \
./configure --prefix=/home/john/vips --disable-introspection \
--enable-debug=no
2014-03-20 15:52:06 +01:00
Static analysis with:
$ cppcheck --force --enable=style . &> cppcheck.log
2012-06-29 13:20:50 +02:00
# Dependencies
2007-08-29 18:23:50 +02:00
2014-06-27 14:11:57 +02:00
libvips has to have gettext, glib-2.x and libxml-2.0. The build system
needs sh, pkg-config, swig, gtk-doc-tools, automake, gobject-introspection
and gnu make.
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`,
so make sure that is working.
2007-08-29 18:23:50 +02:00
libtiff and libjpeg do not usually use pkg-config so libvips looks 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
2008-10-11 23:29:16 +02:00
./configure --prefix=/Users/john/vips \
--with-tiff-includes=/opt/local/include \
--with-tiff-libraries=/opt/local/lib \
--with-jpeg-includes=/opt/local/include \
--with-jpeg-libraries=/opt/local/lib
or perhaps:
CFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \
CXXFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \
./configure --without-python --prefix=/Users/john/vips
2007-08-29 18:23:50 +02:00
to get libvips to see your builds.
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
## libjpeg
The IJG JPEG library.
## libexif
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
## libgsf-1
If available, libvips adds support for creating image pyramids with dzsave.
2012-06-29 13:20:50 +02:00
## libtiff
The TIFF library. It needs to be built with support for JPEG and
ZIP compression. 3.4b037 and later are known to be OK.
## fftw3
If libvips finds this library, it uses it for fourier transforms. It
can also use fftw2, but 3 is faster and more accurate.
## lcms2, lcms
If present, im_icc_import(), _export() and _transform() are available
for transforming images with ICC profiles. If lcms2 is available,
2012-06-29 13:36:56 +02:00
it is used in preference to lcms since it is faster.
2012-06-29 13:20:50 +02:00
## Large files
libvips uses the standard autoconf tests to work out how to support
large files (>2GB) on your system. Any reasonably recent *nix should
be OK.
## libpng
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
2012-06-29 13:20:50 +02:00
## libMagick, or optionally GraphicsMagick
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
if available, libvips adds support for loading all libMagick supported
image file types (about 80 different formats). Use
2012-06-29 13:36:56 +02:00
`--with-magickpackage` to build against graphicsmagick instead.
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +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
2012-06-29 13:20:50 +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
2012-06-29 13:20:50 +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
2012-06-29 13:20:50 +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-01-26 15:58:49 +01:00
## libwebp
If available, vips can load and save WebP images.
2012-06-29 13:20:50 +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
2012-06-29 13:20:50 +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
files: Aperio, Hamamatsu, Leica, MIRAX, Sakura, Trestle, and Ventana.
2007-08-29 18:23:50 +02:00
2012-06-29 13:20:50 +02:00
## swig, python, python-dev
2011-12-08 20:49:53 +01:00
2012-06-29 13:36:56 +02:00
If available, we build the python binding too.
2007-08-29 18:23:50 +02:00
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.