Merge branch 'master' into close-input-early
This commit is contained in:
John Cupitt
commit
a0c8417109
55
README.md
55
README.md
@ -3,32 +3,43 @@
|
||||
[](https://travis-ci.org/jcupitt/libvips)
|
||||
[](https://scan.coverity.com/projects/jcupitt-libvips)
|
||||
|
||||
libvips is a 2D image processing library. Compared to
|
||||
similar libraries, [libvips runs quickly and uses little
|
||||
libvips is a [demand-driven, horizontally
|
||||
threaded](https://github.com/jcupitt/libvips/wiki/Why-is-libvips-quick)
|
||||
image processing library. Compared to similar
|
||||
libraries, [libvips runs quickly and uses little
|
||||
memory](https://github.com/jcupitt/libvips/wiki/Speed-and-memory-use).
|
||||
libvips is licensed under the LGPL 2.1+.
|
||||
libvips is licensed under the [LGPL
|
||||
2.1+](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html).
|
||||
|
||||
It has around 300 operations covering arithmetic, histograms, convolutions,
|
||||
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
|
||||
JPEG, TIFF, PNG, WebP, FITS, Matlab, OpenEXR, PDF, SVG, HDR, PPM, CSV, GIF,
|
||||
Analyze, Nifti, DeepZoom, and OpenSlide. It can also load and save images via
|
||||
ImageMagick or GraphicsMagick.
|
||||
It has around [300 operations](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 formats](API/current/VipsImage.html#VipsBandFormat),
|
||||
from 8-bit int to 128-bit complex. Images can have any number of bands.
|
||||
It supports a good range of image formats, including JPEG, TIFF,
|
||||
PNG, WebP, FITS, Matlab, OpenEXR, PDF, SVG, HDR, PPM, CSV, GIF, Analyze,
|
||||
NIfTI, DeepZoom, and OpenSlide. It can also load images via ImageMagick or
|
||||
GraphicsMagick, letting it load formats like DICOM.
|
||||
|
||||
It has APIs for
|
||||
[C](http://jcupitt.github.io/libvips/API/current/using-from-c.html) and
|
||||
[C++](http://jcupitt.github.io/libvips/API/current/using-from-cpp.html)
|
||||
and a [command-line
|
||||
interface](http://jcupitt.github.io/libvips/API/current/using-cli.html).
|
||||
Bindings are available for [Python](https://pypi.python.org/pypi/pyvips),
|
||||
[Ruby](https://rubygems.org/gems/ruby-vips),
|
||||
It comes with bindings for [C](API/current/using-from-c.html),
|
||||
[C++](API/current/using-from-cpp.html),
|
||||
and the [command-line](API/current/using-cli.html). Full bindings
|
||||
are available for [Ruby](https://rubygems.org/gems/ruby-vips),
|
||||
[Python](https://pypi.python.org/pypi/pyvips),
|
||||
[PHP](https://github.com/jcupitt/php-vips),
|
||||
[Go](https://github.com/davidbyttow/govips),
|
||||
[Lua](https://github.com/jcupitt/lua-vips), JavaScript and others. There is
|
||||
full [documentation](http://jcupitt.github.io/libvips/API/current).
|
||||
There are several GUIs as well, see the [VIPS
|
||||
website](http://jcupitt.github.io/libvips).
|
||||
[.NET](https://www.nuget.org/packages/NetVips),
|
||||
[Go](https://github.com/davidbyttow/govips), and
|
||||
[Lua](https://github.com/jcupitt/lua-vips). libvips
|
||||
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),
|
||||
[carrierwave-vips](https://github.com/eltiare/carrierwave-vips),
|
||||
[mediawiki](http://www.mediawiki.org/wiki/Extension:VipsScaler),
|
||||
[PhotoFlow](https://github.com/aferrero2707/PhotoFlow) and others.
|
||||
The official libvips GUI is [nip2](https://github.com/jcupitt/nip2),
|
||||
a strange combination of a spreadsheet and an photo editor.
|
||||
|
||||
There are packages for most unix-like operating systems and binaries for
|
||||
Windows and OS X.
|
||||
|
||||
@ -91,27 +91,6 @@ $ vips shrink fred.png jim.png 10 10
|
||||
This is done automatically in command-line operation. In programs, you need to set <literal>access</literal> to #VIPS_ACCESS_SEQUENTIAL in calls to functions like vips_image_new_from_file().
|
||||
</para>
|
||||
</refsect3>
|
||||
<refsect3 id="debugging">
|
||||
<title>Debugging</title>
|
||||
<para>
|
||||
There are a few flags you can use to find out what libvips is doing.
|
||||
</para>
|
||||
<para>
|
||||
<literal>--vips-leak</literal> This makes libvips test for leaks on program exit. It checks for images which haven’t been closed and also (usefully) shows the memory high-water mark. It counts all memory allocated in libvips for pixel buffers.
|
||||
</para>
|
||||
<para>
|
||||
<literal>--vips-progress</literal> This makes libvips show a crude progress bar for every major image loop, with destination and elapsed time. You can see whether images are going to disc or to memory and how long the decompression is taking.
|
||||
</para>
|
||||
<para>
|
||||
`–vips-cache-trace This shows a line for every vips operation that executes, with arguments. It’s part of vips8, so it doesn’t display vips7 operations, sadly.
|
||||
</para>
|
||||
</refsect3>
|
||||
<refsect3 id="summary">
|
||||
<title>Summary</title>
|
||||
<para>
|
||||
libvips tries hard to do the quickest thing in every case, but will sometimes fail. You can prod it in the right direction with a mixture of hints and flags to the load system.
|
||||
</para>
|
||||
</refsect3>
|
||||
|
||||
|
||||
</refentry>
|
||||
|
||||
@ -138,7 +138,7 @@ g_object_unref( region );
|
||||
<refsect3 id="data-sources">
|
||||
<title>Data sources</title>
|
||||
<para>
|
||||
VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. A post on the libvips blog <ulink url="http://libvips.blogspot.co.uk/2012/06/how-libvips-opens-file.html">explains how libvips opens a file</ulink>. One of the sources uses the <ulink url="http://www.imagemagick.org">ImageMagick</ulink> (or optionally <ulink url="http://www.graphicsmagick.org">GraphicsMagick</ulink>) library, so VIPS can read any image format that these libraries can read.
|
||||
VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. Another section in these docs explains <ulink url="How-it-opens-files.html">how libvips opens a file</ulink>. One of the sources uses the <ulink url="http://www.imagemagick.org">ImageMagick</ulink> (or optionally <ulink url="http://www.graphicsmagick.org">GraphicsMagick</ulink>) library, so VIPS can read any image format that these libraries can read.
|
||||
</para>
|
||||
<para>
|
||||
VIPS images are held on disc as a 64-byte header containing basic image information like width, height, bands and format, then the image data as a single large block of pixels, left-to-right and top-to-bottom, then an XML extension block holding all the image metadata, such as ICC profiles and EXIF blocks.
|
||||
|
||||
@ -77,6 +77,9 @@ $ vipsthumbnail shark.jpg --size 200x
|
||||
<para>
|
||||
You can append <literal><</literal> or <literal>></literal> to mean only resize if the image is smaller or larger than the target.
|
||||
</para>
|
||||
<para>
|
||||
You can append <literal>!</literal> to force a resize to the exact target size, breaking the aspect ratio.
|
||||
</para>
|
||||
</refsect3>
|
||||
<refsect3 id="cropping">
|
||||
<title>Cropping</title>
|
||||
@ -185,7 +188,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png
|
||||
You can give options to the image write operation as a list of comma-separated arguments in square brackets. For example:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ vipsthumbnail fred.jpg ../jim.tif -o > tn_%s.jpg[Q=90,optimize_coding]
|
||||
$ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.jpg[Q=90,optimize_coding]
|
||||
</programlisting>
|
||||
<para>
|
||||
will write jpeg images with quality 90, and will turn on the libjpeg coding optimizer.
|
||||
|
||||
@ -11,18 +11,18 @@
|
||||
<refnamediv> <refname>Binding</refname> <refpurpose>Writing bindings for libvips</refpurpose> </refnamediv>
|
||||
</para>
|
||||
<para>
|
||||
There are full libvips bindings for quite a few environments now: C, C++, command-line, Ruby, PHP, Python and JavaScript (node).
|
||||
There are full libvips bindings for quite a few environments now: C, C++, command-line, Ruby, PHP, Lua, Python and JavaScript (node).
|
||||
</para>
|
||||
<para>
|
||||
This chapter runs through the four main styles that have been found to work well. If you want to write a new binding, one of these should be close to what you need.
|
||||
</para>
|
||||
<refsect3 id="c-api">
|
||||
<title>C API</title>
|
||||
<refsect3 id="dont-bind-the-top-level-c-api">
|
||||
<title>Don’t bind the top-level C API</title>
|
||||
<para>
|
||||
The libvips C API (vips_add() and so on) is very inconvenient to use from other languages due to its heavy use of varargs.
|
||||
The libvips C API (vips_add() and so on) is very inconvenient and dangerous to use from other languages due to its heavy use of varargs.
|
||||
</para>
|
||||
<para>
|
||||
It’s much better to use the layer below. This lower layer is structured as: create operator, set parameters, execute, extract results. For example, you can execute vips_invert() like this:
|
||||
It’s much better to use the layer below. This lower layer is structured as create operator, set parameters, execute, extract results. For example, you can execute vips_invert() like this:
|
||||
</para>
|
||||
<programlisting language="c">
|
||||
/* compile with
|
||||
@ -112,7 +112,7 @@ main( int argc, char **argv )
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
libvips has a couple of extra things to let you fetch the arguments and types of an operator. Use vips_lib.vips_argument_map() to loop over all the arguments of an operator, and vips_object_get_argument() to fetch the type and flags of a specific argument.
|
||||
libvips has a couple of extra things to let you examine the arguments and types of an operator at runtime. Use vips_lib.vips_argument_map() to loop over all the arguments of an operator, and vips_object_get_argument() to fetch the type and flags of a specific argument.
|
||||
</para>
|
||||
<para>
|
||||
Use vips_operation_get_flags() to get general information about an operator.
|
||||
@ -139,7 +139,7 @@ VImage VImage::invert( VOption *options )
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
So from C++ you can call any libvips operator, though without type-safety, with <literal>VImage::call()</literal>, or use the member functions on <literal>VImage</literal> to get type-safe calls for at least the required operator arguments.
|
||||
So from C++ you can call any libvips operator (though without type-safety) with <literal>VImage::call()</literal>, or use the member functions on <literal>VImage</literal> to get type-safe calls for at least the required operator arguments.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>VImage</literal> class also adds automatic reference counting, constant expansion, operator overloads, and various other useful features.
|
||||
@ -151,7 +151,7 @@ VImage VImage::invert( VOption *options )
|
||||
Languages like Ruby, Python, JavaScript and Lua can’t call C directly, but they do support FFI. The bindings for these languages work rather like C++, but use FFI to call into libvips and run operations.
|
||||
</para>
|
||||
<para>
|
||||
Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the <literal>Image</literal> class as libvips operators. This makes these bindings self-writing: they only contain a small amount of codeand just expose everything they find in the libvips class hierarchy.
|
||||
Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the <literal>Image</literal> class as libvips operators. This makes these bindings self-writing: they only contain a small amount of code and just expose everything they find in the libvips class hierarchy.
|
||||
</para>
|
||||
</refsect3>
|
||||
<refsect3 id="dynamic-langauge-without-ffi">
|
||||
@ -161,7 +161,7 @@ VImage VImage::invert( VOption *options )
|
||||
</para>
|
||||
</refsect3>
|
||||
<refsect3 id="gobject-introspection">
|
||||
<title><literal>gobject-introspection</literal></title>
|
||||
<title>gobject-introspection</title>
|
||||
<para>
|
||||
The C source code to libvips has been marked up with special comments describing the interface in a standard way. These comments are read by the <literal>gobject-introspection</literal> package when libvips is compiled and used to generate a typelib, a description of how to call the library. Many languages have gobject-introspection packages: all you need to do to call libvips from your favorite language is to start g-o-i, load the libvips typelib, and you should have the whole library available. For example, from Python it’s as simple as:
|
||||
</para>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user