<refnamediv><refname><literal>vipsthumbnail</literal></refname><refpurpose>Introduction to <literal>vipsthumbnail</literal>, with examples</refpurpose></refnamediv>
</para>
<para>
libvips ships with a handy command-line image thumbnailer, <literal>vipsthumbnail</literal>. This page introduces it, with some examples.
The thumbnailing functionality is implemented by <literal>vips_thumbnail()</literal> and <literal>vips_thumbnail_buffer()</literal> (which thumbnails an image held as a string), see the docs for details. You can use these functions from any language with a libvips binding. For example, from PHP you could write:
<literal>vipsthumbnail</literal> supports the usual range of vips command-line options. A few of them are useful:
</para>
<para>
<literal>--vips-cache-trace</literal> shows each operation as libvips starts it. It can be handy to see exactly what operations <literal>vipsthumbnail</literal> is running for you.
</para>
<para>
<literal>--vips-leak</literal> turns on the libvips memory leak checker. As well as reporting leaks (hopefully there are none) it also tracks and reports peak memory use.
</para>
<para>
<literal>--vips-progress</literal> runs a progress indicator during computation. It can be useful to see where libvips is looping and how often.
</para>
<para>
<literal>--vips-info</literal> shows a higher level view of the operations that <literal>vipsthumbnail</literal> is running.
will make a thumbnail for every jpeg in the current directory. See the <linklinkend="output-directory">Output directory</link> section below to see how to change where thumbnails are written.
<literal>vipsthumbnail</literal> will process images one after the other. You can get a good speedup by running several <literal>vipsthumbnail</literal>s in parallel, depending on how much load you want to put on your system. For example:
<literal>vipsthumbnail</literal> normally shrinks images to fit within the box set by <literal>--size</literal>. You can use the <literal>--smartcrop</literal> option to crop to fill the box instead. Excess pixels are trimmed away using the strategy you set. For example:
Where <literal>owl.jpg</literal> is an off-centre composition:
</para>
<figure>
<mediaobject>
<imageobject>
<imagedatafileref="owl.jpg"/>
</imageobject>
<textobject><phrase></phrase></textobject>
</mediaobject>
</figure>
<para>
Gives this result:
</para>
<figure>
<mediaobject>
<imageobject>
<imagedatafileref="tn_owl.jpg"/>
</imageobject>
<textobject><phrase></phrase></textobject>
</mediaobject>
</figure>
<para>
First it shrinks the image to get the vertical axis to 128 pixels, then crops down to 128 pixels across using the <literal>attention</literal> strategy. This one searches the image for features which might catch a human eye, see <literal>vips_smartcrop()</literal> for details.
Shrinking images involves combining many pixels into one. Arithmetic averaging really ought to be in terms of the number of photons, but (for historical reasons) the values stored in image files are usually related to the voltage that should be applied to the electron gun in a CRT display.
<literal>vipsthumbnail</literal> has an option to perform image shrinking in linear space, that is, a colourspace where values are proportional to photon numbers. For example:
The downside is that in linear mode, none of the very fast shrink-on-load tricks that <literal>vipsthumbnail</literal> normally uses are possible, since the shrinking is done at encode time, not decode time, and is done in terms of CRT voltage, not photons. This can make linear light thumbnailing of large images extremely slow.
</para>
<para>
For example, for a 10,000 x 10,000 pixel JPEG I see:
You set the thumbnail write parameters with the <literal>-o</literal> option. This is a pattern which the input filename is pasted into to produce the output filename. For example:
</para>
<programlisting>
$ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg
</programlisting>
<para>
For each of the files to be thumbnailed, <literal>vipsthumbnail</literal> will drop the extension (<literal>.jpg</literal> and <literal>.tif</literal> in this case) and then substitute the name into the <literal>-o</literal> option, replacing the <literal>%s</literal> So this example will write thumbnails to <literal>tn_fred.jpg</literal> and <literal>tn_jim.jpg</literal>.
</para>
<para>
If the pattern given to <literal>-o</literal> is an absolute path, any path components are dropped from the input filenames. This lets you write all of your thumbnails to a specific directory, if you want. For example:
The <literal>strip</literal> option is especially useful. Many image have very large IPCT, ICC or XMP metadata items embedded in them, and removing these can give a large saving.
</para>
<para>
For example:
</para>
<programlisting>
$ vipsthumbnail 42-32157534.jpg
$ ls -l tn_42-32157534.jpg
-rw-r–r– 1 john john 6682 Nov 12 21:27 tn_42-32157534.jpg
</programlisting>
<para>
<literal>strip</literal> almost halves the size of the thumbnail:
<literal>vipsthumbnail</literal> will optionally put images through LittleCMS for you. You can use this to move all thumbnails to the same colour space. All web browsers assume that images without an ICC profile are in sRGB colourspace, so if you move your thumbnails to sRGB, you can strip all the embedded profiles. This can save several kb per thumbnail.
</para>
<para>
For example:
</para>
<programlisting>
$ vipsthumbnail shark.jpg
$ ls -l tn_shark.jpg
-rw-r–r– 1 john john 7295 Nov 9 14:33 tn_shark.jpg
</programlisting>
<para>
Now encode with sRGB and delete any embedded profile:
You can also specify a fallback input profile to use if the image has no embedded one. This can often happen with CMYK images, producing an error message like:
</para>
<programlisting>
$ vipsthumbnail kgdev.jpg
vipsthumbnail: unable to thumbnail kgdev.jpg
vips_colourspace: no known route from 'cmyk' to 'srgb'
</programlisting>
<para>
If you supply a CMYK profile, it will be able to convert the image, for example:
Many JPEG files have a hint set in the header giving the image orientation. If you strip out the metadata, this hint will be lost, and the image will appear to be rotated.
</para>
<para>
If you use the <literal>--rotate</literal> option, <literal>vipsthumbnail</literal> examines the image header and if there’s an orientation tag, applies and removes it.
