1# libvips : an image processing library 2 3[![CI](https://github.com/libvips/libvips/workflows/CI/badge.svg)](https://github.com/libvips/libvips/actions) 4[![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) 5[![Coverity Status](https://scan.coverity.com/projects/6503/badge.svg)](https://scan.coverity.com/projects/jcupitt-libvips) 6[![Gitter](https://badges.gitter.im/libvips/devchat.svg)](https://gitter.im/libvips/devchat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 7 8# Introduction 9 10libvips is a [demand-driven, horizontally 11threaded](https://github.com/libvips/libvips/wiki/Why-is-libvips-quick) 12image processing library. Compared to similar 13libraries, [libvips runs quickly and uses little 14memory](https://github.com/libvips/libvips/wiki/Speed-and-memory-use). 15libvips is licensed under the [LGPL 162.1+](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html). 17 18It has around [300 19operations](https://libvips.github.io/libvips/API/current/func-list.html) 20covering arithmetic, histograms, convolution, morphological 21operations, frequency filtering, colour, resampling, 22statistics and others. It supports a large range of [numeric 23types](https://libvips.github.io/libvips/API/current/VipsImage.html#VipsBandFormat), 24from 8-bit int to 128-bit complex. Images can have any number of bands. 25It supports a good range of image formats, including JPEG, JPEG2000, JPEG-XL, 26TIFF, PNG, WebP, HEIC, AVIF, FITS, Matlab, OpenEXR, PDF, SVG, HDR, PPM / PGM / 27PFM, CSV, GIF, Analyze, NIfTI, DeepZoom, and OpenSlide. It can also load 28images via ImageMagick or GraphicsMagick, letting it work with formats 29like DICOM. 30 31It comes with bindings for 32[C](https://libvips.github.io/libvips/API/current/using-from-c.html), 33[C++](https://libvips.github.io/libvips/API/current/using-from-cpp.html), 34and the 35[command-line](https://libvips.github.io/libvips/API/current/using-cli.html). 36Full bindings are available for [Ruby](https://rubygems.org/gems/ruby-vips), 37[Python](https://pypi.python.org/pypi/pyvips), 38[PHP](https://github.com/libvips/php-vips), 39[C# / .NET](https://www.nuget.org/packages/NetVips), 40[Go](https://github.com/davidbyttow/govips), and 41[Lua](https://github.com/libvips/lua-vips). libvips 42is used as an image processing engine by [sharp 43(on node.js)](https://www.npmjs.org/package/sharp), 44[bimg](https://github.com/h2non/bimg), [sharp 45for Go](https://github.com/DAddYE/vips), [Ruby on 46Rails](https://edgeguides.rubyonrails.org/active_storage_overview.html), 47[carrierwave-vips](https://github.com/eltiare/carrierwave-vips), 48[mediawiki](https://www.mediawiki.org/wiki/Extension:VipsScaler), 49[PhotoFlow](https://github.com/aferrero2707/PhotoFlow) and others. 50The official libvips GUI is [nip2](https://github.com/libvips/nip2), 51a strange combination of a spreadsheet and a photo editor. 52 53# Install 54 55There are packages for most Unix-like operating systems, including 56macOS. Check your package manager. 57 58There are binaries for Windows in 59[releases](https://github.com/libvips/libvips/releases). 60 61The [libvips website](https://libvips.github.io/libvips) has [detailed 62install notes](https://libvips.github.io/libvips/install.html). 63 64# Building libvips from a source tarball 65 66We keep pre-baked tarballs in 67[releases](https://github.com/libvips/libvips/releases). 68 69Untar, then in the libvips directory you should just be able to do: 70 71 ./configure 72 73Check the summary at the end of `configure` carefully. libvips must have 74`build-essential`, `pkg-config`, `libglib2.0-dev`, `libexpat1-dev`. 75 76You'll need the dev packages for the file format support you want. For basic 77jpeg and tiff support, you'll need `libtiff5-dev`, `libjpeg-turbo8-dev`, 78and `libgsf-1-dev`. See the **Dependencies** section below for a full list 79of the things that libvips can be configured to use. 80 81Once `configure` is looking OK, compile and install with the usual: 82 83 make 84 sudo make install 85 86By default this will install files to `/usr/local`. 87 88# Testing 89 90Run the test suite with: 91 92 make check 93 94Run a specific test with: 95 96 pytest test/test-suite/test_foreign.py -k test_tiff 97 98# Building libvips from git 99 100Clone the latest sources with: 101 102 git clone git://github.com/libvips/libvips.git 103 104Building from git needs more packages -- you'll need at least `gtk-doc` 105and `gobject-introspection`, see the dependencies section below. For example: 106 107 brew install gtk-doc 108 109Then generate the build system with: 110 111 ./autogen.sh --prefix=/home/john/vips 112 113Debug build: 114 115 CFLAGS="-g -Wall" CXXFLAGS="-g -Wall" \ 116 ./configure --prefix=/home/john/vips --enable-debug 117 make 118 make install 119 120# Built-in loaders 121 122libvips has a number of built-in loaders and savers. You can disable these if 123you wish, for example: 124 125 ./configure --prefix=/Users/john/vips --without-nsgif --without-ppm 126 127# Dependencies 128 129libvips has to have `libglib2.0-dev` and `libexpat1-dev`. Other dependencies 130are optional. 131 132## Optional dependencies 133 134If suitable versions are found, libvips will add support for the following 135libraries automatically. See `./configure --help` for a set of flags to 136control library detection. Packages are generally found with `pkg-config`, 137so make sure that is working. 138 139Libraries like nifti do not use `pkg-config` so libvips will also 140look for them in the default path and in `$prefix`. If you have installed 141your own versions of these libraries in a different location, libvips will 142not see them. Use switches to libvips configure like: 143 144 ./configure --prefix=/Users/john/vips \ 145 --with-nifti-includes=/opt/local/include \ 146 --with-nifti-libraries=/opt/local/lib 147 148or perhaps: 149 150 CFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \ 151 CXXFLAGS="-g -Wall -I/opt/local/include -L/opt/local/lib" \ 152 ./configure --prefix=/Users/john/vips 153 154### libjpeg 155 156The IJG JPEG library. Use the `-turbo` version if you can. 157 158### libexif 159 160If available, libvips adds support for EXIF metadata in JPEG files. 161 162### librsvg 163 164The usual SVG loader. If this is not present, vips will try to load SVGs 165via imagemagick instead. 166 167### PDFium 168 169If present, libvips will attempt to load PDFs with PDFium. Download the 170prebuilt pdfium binary from: 171 172 https://github.com/bblanchon/pdfium-binaries 173 174Untar to the libvips install prefix, for example: 175 176 cd ~/vips 177 tar xf ~/pdfium-linux.tgz 178 179Create a `pdfium.pc` like this (update the version number): 180 181 VIPSHOME=/home/john/vips 182 cat > $VIPSHOME/lib/pkgconfig/pdfium.pc << EOF 183 prefix=$VIPSHOME 184 exec_prefix=\${prefix} 185 libdir=\${exec_prefix}/lib 186 includedir=\${prefix}/include 187 Name: pdfium 188 Description: pdfium 189 Version: 4290 190 Requires: 191 Libs: -L\${libdir} -lpdfium 192 Cflags: -I\${includedir} 193 EOF 194 195If PDFium is not detected, libvips will look for poppler-glib instead. 196 197### poppler-glib 198 199The Poppler PDF renderer, with a glib API. If this is not present, vips 200will try to load PDFs via imagemagick. 201 202### libgsf-1 203 204If available, libvips adds support for creating image pyramids with `dzsave`. 205 206### libtiff 207 208The TIFF library. It needs to be built with support for JPEG and 209ZIP compression. 3.4b037 and later are known to be OK. 210 211### fftw3 212 213If libvips finds this library, it uses it for fourier transforms. 214 215### lcms2 216 217If present, `vips_icc_import()`, `vips_icc_export()` and `vips_icc_transform()` 218can be used to manipulate images with ICC profiles. 219 220### libspng 221 222If present, libvips will load PNG files using libspng. At the moment, libpng 223is still necessary for save. 224 225### libpng 226 227If libspng is not present and libpng is, libvips will load PNG files with 228libpng. It will always save PNG files with libpng. 229 230### libimagequant 231 232If present, libvips can write 8-bit palette-ised PNGs. 233 234### ImageMagick, or optionally GraphicsMagick 235 236If available, libvips adds support for loading all libMagick-supported 237image file types. Use `--with-magickpackage=GraphicsMagick` to build against 238graphicsmagick instead. 239 240Imagemagick 6.9+ needs to have been built with `--with-modules`. Most packaged 241IMs are, I think. 242 243If you are going to be using libvips with untrusted images, perhaps in a 244web server, for example, you should consider the security implications of 245enabling a package with such a large attack surface. 246 247### pangocairo 248 249If available, libvips adds support for text rendering. You need the 250package pangocairo in `pkg-config --list-all`. 251 252### orc-0.4 253 254If available, vips will accelerate some operations with this run-time 255compiler. 256 257### matio 258 259If available, vips can load images from Matlab save files. 260 261### cfitsio 262 263If available, vips can load FITS images. 264 265### libwebp 266 267If available, vips can load and save WebP images. 268 269### libniftiio 270 271If available, vips can load and save NIfTI images. 272 273### OpenEXR 274 275If available, libvips will directly read (but not write, sadly) 276OpenEXR images. 277 278### OpenJPEG 279 280If available, libvips will read and write JPEG2000 images. 281 282### libjxl 283 284If available, libvips will read and write JPEG-XL images. 285 286### OpenSlide 287 288If available, libvips can load OpenSlide-supported virtual slide 289files: Aperio, Hamamatsu, Leica, MIRAX, Sakura, Trestle, and Ventana. 290 291### libheif 292 293If available, libvips can load and save HEIC and AVIF images. Your libheif (in 294turn) needs to be built with the correct decoders and encoders. You can check 295with eg.: 296 297``` 298$ pkg-config libheif --print-variables 299builtin_avif_decoder 300builtin_avif_encoder 301builtin_h265_decoder 302builtin_h265_encoder 303exec_prefix 304includedir 305libdir 306pcfiledir 307prefix 308``` 309 310# Contributors 311 312### Code Contributors 313 314This project exists thanks to all the people who contribute. 315 316<a href="https://github.com/libvips/libvips/graphs/contributors"><img src="https://opencollective.com/libvips/contributors.svg?width=890&button=false" /></a> 317 318### Organizations 319 320Support this project with your organization. Your logo will show up here with a link to your website. 321 322<a href="https://opencollective.com/libvips/organization/0/website"><img src="https://opencollective.com/libvips/organization/0/avatar.svg"></a> 323<a href="https://opencollective.com/libvips/organization/1/website"><img src="https://opencollective.com/libvips/organization/1/avatar.svg"></a> 324<a href="https://opencollective.com/libvips/organization/2/website"><img src="https://opencollective.com/libvips/organization/2/avatar.svg"></a> 325<a href="https://opencollective.com/libvips/organization/3/website"><img src="https://opencollective.com/libvips/organization/3/avatar.svg"></a> 326<a href="https://opencollective.com/libvips/organization/4/website"><img src="https://opencollective.com/libvips/organization/4/avatar.svg"></a> 327<a href="https://opencollective.com/libvips/organization/5/website"><img src="https://opencollective.com/libvips/organization/5/avatar.svg"></a> 328<a href="https://opencollective.com/libvips/organization/6/website"><img src="https://opencollective.com/libvips/organization/6/avatar.svg"></a> 329<a href="https://opencollective.com/libvips/organization/7/website"><img src="https://opencollective.com/libvips/organization/7/avatar.svg"></a> 330<a href="https://opencollective.com/libvips/organization/8/website"><img src="https://opencollective.com/libvips/organization/8/avatar.svg"></a> 331<a href="https://opencollective.com/libvips/organization/9/website"><img src="https://opencollective.com/libvips/organization/9/avatar.svg"></a> 332