sergiotarxz
/
libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

polish docs

This commit is contained in:
John Cupitt 2017-04-01 17:05:05 +01:00
parent a78ef520e2
commit ab7bd3000b
10 changed files with 178 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
TODO
View File

@ -1,5 +1,3 @@
- move "how libvips opens files" into docs?
- not sure about utf8 error messages on win - not sure about utf8 error messages on win
- strange: - strange:

39
doc/How-it-opens-files.md
View File

@ -1,22 +1,33 @@
libvips now has at least four different ways of opening image files, each best <refmeta>
for different file types, file sizes and image use cases. libvips <refentrytitle>Opening files</refentrytitle>
tries hard to pick the best strategy in each case and mostly you don't need <manvolnum>3</manvolnum>
to know what it is doing behind the scenes, except unfortunately when you do. <refmiscinfo>libvips</refmiscinfo>
</refmeta>
This post tries to explain what the different strategies are and when each is <refnamediv>
<refname>Opening</refname>
<refpurpose>How libvips opens files</refpurpose>
</refnamediv>
libvips now has at least four different ways of opening image files, each
best for different file types, file sizes and image use cases. libvips tries
hard to pick the best strategy in each case and mostly you don't need to
know what it is doing behind the scenes, except unfortunately when you do.
This page tries to explain what the different strategies are and when each is
used. If you are running into unexpected memory, disc or CPU use, this might used. If you are running into unexpected memory, disc or CPU use, this might
be helpful. `vips_image_new_from_file()` has the official documentation. be helpful. `vips_image_new_from_file()` has the official documentation.
# Direct access # Direct access
This is the fastest and simplest one. The file is mapped directly into This is the fastest and simplest one. The file is mapped directly into the
the process's address space and can be read with ordinary pointer process's address space and can be read with ordinary pointer access. Small
access. Small files are completely mapped; large files are mapped in a files are completely mapped; large files are mapped in a series of small
series of small windows that are shared and which scroll about as pixels windows that are shared and which scroll about as pixels are read. Files
are read. Files which are accessed like this can be read by many threads which are accessed like this can be read by many threads at once, making
at once, making them especially quick. They also interact well with the them especially quick. They also interact well with the computer's operating
computer's operating system: your OS will use spare memory to cache system: your OS will use spare memory to cache recently used chunks of the
recently used chunks of the file, very handy. file.
For this to be possible, the file format needs to be a simple dump of a memory For this to be possible, the file format needs to be a simple dump of a memory
array. libvips supports direct access for vips, 8-bit binary ppm/pbm/pnm, array. libvips supports direct access for vips, 8-bit binary ppm/pbm/pnm,

21
doc/How-it-opens-files.xml
View File

@ -3,28 +3,23 @@
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="How-it-opens-files.md"> <refentry id="How-it-opens-files.md">
<refmeta>
<refentrytitle>How-it-opens-files.md</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libvips</refname>
<refpurpose>How-it-opens-files.md</refpurpose>
</refnamediv>
<para>
<refmeta> <refentrytitle>Opening files</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>libvips</refmiscinfo> </refmeta>
</para>
<para>
<refnamediv> <refname>Opening</refname> <refpurpose>How libvips opens files</refpurpose> </refnamediv>
</para>
<para> <para>
libvips now has at least four different ways of opening image files, each best for different file types, file sizes and image use cases. libvips tries hard to pick the best strategy in each case and mostly you don’t need to know what it is doing behind the scenes, except unfortunately when you do. libvips now has at least four different ways of opening image files, each best for different file types, file sizes and image use cases. libvips tries hard to pick the best strategy in each case and mostly you don’t need to know what it is doing behind the scenes, except unfortunately when you do.
</para> </para>
<para> <para>
This post tries to explain what the different strategies are and when each is used. If you are running into unexpected memory, disc or CPU use, this might be helpful. <literal>vips_image_new_from_file()</literal> has the official documentation. This page tries to explain what the different strategies are and when each is used. If you are running into unexpected memory, disc or CPU use, this might be helpful. <literal>vips_image_new_from_file()</literal> has the official documentation.
</para> </para>
<refsect3 id="direct-access"> <refsect3 id="direct-access">
<title>Direct access</title> <title>Direct access</title>
<para> <para>
This is the fastest and simplest one. The file is mapped directly into the process’s address space and can be read with ordinary pointer access. Small files are completely mapped; large files are mapped in a series of small windows that are shared and which scroll about as pixels are read. Files which are accessed like this can be read by many threads at once, making them especially quick. They also interact well with the computer’s operating system: your OS will use spare memory to cache recently used chunks of the file, very handy. This is the fastest and simplest one. The file is mapped directly into the process’s address space and can be read with ordinary pointer access. Small files are completely mapped; large files are mapped in a series of small windows that are shared and which scroll about as pixels are read. Files which are accessed like this can be read by many threads at once, making them especially quick. They also interact well with the computer’s operating system: your OS will use spare memory to cache recently used chunks of the file.
</para> </para>
<para> <para>
For this to be possible, the file format needs to be a simple dump of a memory array. libvips supports direct access for vips, 8-bit binary ppm/pbm/pnm, analyse and raw. For this to be possible, the file format needs to be a simple dump of a memory array. libvips supports direct access for vips, 8-bit binary ppm/pbm/pnm, analyse and raw.

15
doc/How-it-works.md
View File

@ -1,3 +1,14 @@
<refmeta>
<refentrytitle>How libvips works</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Internals</refname>
<refpurpose>A high-level technical overview of libvips's evaluation system</refpurpose>
</refnamediv>
Compared to most image processing libraries, VIPS needs little RAM and runs Compared to most image processing libraries, VIPS needs little RAM and runs
quickly, especially on machines with more than one CPU. VIPS achieves this quickly, especially on machines with more than one CPU. VIPS achieves this
improvement by only keeping the pixels currently being processed in RAM improvement by only keeping the pixels currently being processed in RAM
@ -152,8 +163,8 @@ from FITS images and from tiled OpenEXR images. VIPS will automatically
unpack other formats to temporary disc files for you but this can unpack other formats to temporary disc files for you but this can
obviously generate a lot of disc traffic. It also has a special obviously generate a lot of disc traffic. It also has a special
sequential mode for streaming operations on non-random-access sequential mode for streaming operations on non-random-access
formats. A post on the libvips blog [explains how libvips opens a formats. Another section in these docs explains [how libvips opens a
file](http://libvips.blogspot.co.uk/2012/06/how-libvips-opens-file.html). One file](How-it-opens-files.html). One
of the sources uses the [ImageMagick](http://www.imagemagick.org) (or of the sources uses the [ImageMagick](http://www.imagemagick.org) (or
optionally [GraphicsMagick](http://www.graphicsmagick.org)) library, so optionally [GraphicsMagick](http://www.graphicsmagick.org)) library, so
VIPS can read any image format that these libraries can read. VIPS can read any image format that these libraries can read.

17
doc/How-it-works.xml
View File

@ -3,18 +3,13 @@
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="How-it-works.md"> <refentry id="How-it-works.md">
<refmeta>
<refentrytitle>How-it-works.md</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libvips</refname>
<refpurpose>How-it-works.md</refpurpose>
</refnamediv>
<para>
<refmeta> <refentrytitle>How libvips works</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>libvips</refmiscinfo> </refmeta>
</para>
<para>
<refnamediv> <refname>Internals</refname> <refpurpose>A high-level technical overview of libvips’s evaluation system</refpurpose> </refnamediv>
</para>
<para> <para>
Compared to most image processing libraries, VIPS needs little RAM and runs quickly, especially on machines with more than one CPU. VIPS achieves this improvement by only keeping the pixels currently being processed in RAM and by having an efficient, threaded image IO system. This page explains how these features are implemented. Compared to most image processing libraries, VIPS needs little RAM and runs quickly, especially on machines with more than one CPU. VIPS achieves this improvement by only keeping the pixels currently being processed in RAM and by having an efficient, threaded image IO system. This page explains how these features are implemented.
</para> </para>

11
doc/Making-image-pyramids.md
View File

@ -1,3 +1,14 @@
<refmeta>
<refentrytitle>Image pyramids</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Pyramids</refname>
<refpurpose>How to use libvips to make image pyramids</refpurpose>
</refnamediv>
libvips includes `vips_dzsave()`, an operation that can build image pyramids libvips includes `vips_dzsave()`, an operation that can build image pyramids
compatible with [DeepZoom](http://en.wikipedia.org/wiki/Deep_Zoom), Zoomify compatible with [DeepZoom](http://en.wikipedia.org/wiki/Deep_Zoom), Zoomify
and [Google Maps](https://developers.google.com/maps/) image viewers. It's and [Google Maps](https://developers.google.com/maps/) image viewers. It's

17
doc/Making-image-pyramids.xml
View File

@ -3,18 +3,13 @@
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Making-image-pyramids.md"> <refentry id="Making-image-pyramids.md">
<refmeta>
<refentrytitle>Making-image-pyramids.md</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libvips</refname>
<refpurpose>Making-image-pyramids.md</refpurpose>
</refnamediv>
<para>
<refmeta> <refentrytitle>Image pyramids</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>libvips</refmiscinfo> </refmeta>
</para>
<para>
<refnamediv> <refname>Pyramids</refname> <refpurpose>How to use libvips to make image pyramids</refpurpose> </refnamediv>
</para>
<para> <para>
libvips includes <literal>vips_dzsave()</literal>, an operation that can build image pyramids compatible with <ulink url="http://en.wikipedia.org/wiki/Deep_Zoom">DeepZoom</ulink>, Zoomify and <ulink url="https://developers.google.com/maps/">Google Maps</ulink> image viewers. It’s fast and can generate pyramids for large images using only a small amount of memory. libvips includes <literal>vips_dzsave()</literal>, an operation that can build image pyramids compatible with <ulink url="http://en.wikipedia.org/wiki/Deep_Zoom">DeepZoom</ulink>, Zoomify and <ulink url="https://developers.google.com/maps/">Google Maps</ulink> image viewers. It’s fast and can generate pyramids for large images using only a small amount of memory.
</para> </para>

96
doc/Using-vipsthumbnail.md
View File

@ -1,10 +1,27 @@
libvips ships with a handy command-line image thumbnailer, `vipsthumbnail`. <refmeta>
This page introduces it with examples. <refentrytitle>Using `vipsthumbnail`</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
The thumbnailing functionality is implemeted by <refnamediv>
`vips_thumbnail()` and <refname>`vipsthumbnail`</refname>
`vips_thumbnail_buffer()`, see the docs for details. You can use these <refpurpose>Introduction to `vipsthumbnail`, with examples</refpurpose>
functions from any language with a libvips binding. </refnamediv>
libvips ships with a handy command-line image thumbnailer, `vipsthumbnail`.
This page introduces it, with some examples.
The thumbnailing functionality is implemented by `vips_thumbnail()` and
`vips_thumbnail_buffer()` (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:
```php
$filename = ...;
$image = Vips\Image::thumbnail($filename, 200, ["height" => 200]);
$image.writeToFile("my-thumbnail.jpg");
```
# libvips options # libvips options
@ -25,15 +42,15 @@ is running. 
# Looping # Looping
vipsthumbnail can process many images in one operation. For example: `vipsthumbnail` can process many images in one command. For example:
``` ```
$ vipsthumbnail *.jpg $ vipsthumbnail *.jpg
``` ```
will make a thumbnail for every jpeg in the current directory.  See the will make a thumbnail for every jpeg in the current directory.  See the
**Output directory** section below to see how to change where thumbnails [Output directory](#output-directory) section below to see how to change
are written. where thumbnails are written.
`vipsthumbnail` will process images one after the other. You can get a good `vipsthumbnail` will process images one after the other. You can get a good
speedup by running several `vipsthumbnail`s in parallel, depending on how speedup by running several `vipsthumbnail`s in parallel, depending on how
@ -93,7 +110,7 @@ for details.
Shrinking images involves combining many pixels into one. Arithmetic Shrinking images involves combining many pixels into one. Arithmetic
averaging really ought to be in terms of the number of photons, but (for 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 historical reasons) the values stored in image files are usually related
to the voltage that should be applied to a CRT electron gun. to the voltage that should be applied to the electron gun in a CRT display.
`vipsthumbnail` has an option to perform image shrinking in linear space, that `vipsthumbnail` has an option to perform image shrinking in linear space, that
is, a colourspace where values are proportional to photon numbers. For example: is, a colourspace where values are proportional to photon numbers. For example:
@ -103,10 +120,22 @@ $ vipsthumbnail fred.jpg --linear
``` ```
The downside is that in linear mode, none of the very fast shrink-on-load The downside is that in linear mode, none of the very fast shrink-on-load
tricks that `vipsthumbnail` normally uses are possible, since the shrinking tricks that `vipsthumbnail` normally uses are possible, since the shrinking is
done by the image libraries is done at encode time, and done in done at encode time, not decode time, and is done in terms of CRT voltage, not
terms of CRT voltage, not light. This can make linear light thumbnailing of photons. This can make linear light thumbnailing of large images extremely slow.
large images extremely slow.
For example, for a 10,000 x 10,000 pixel JPEG I see:
```
$ time vipsthumbnail wtc.jpg
real 0m0.317s
user 0m0.292s
sys 0m0.016s
$ time vipsthumbnail wtc.jpg --linear
real 0m4.660s
user 0m4.640s
sys 0m0.016s
```
# Output directory # Output directory
@ -118,27 +147,24 @@ produce the output filename. For example:
$ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg $ vipsthumbnail fred.jpg jim.tif -o tn_%s.jpg
``` ```
For each of the files to be thumbnailed, `vipsthumbnail` For each of the files to be thumbnailed, `vipsthumbnail` will drop the
will drop the extension (`.jpg` and `.tif` extension (`.jpg` and `.tif` in this case) and then substitute the name into
in this case) and then substitute the name into the `-o` the `-o` option, replacing the `%s` So this example will write thumbnails to
option, replacing the `%s` `tn_fred.jpg` and `tn_jim.jpg`.
So this example will write thumbnails to `tn_fred.jpg` and `tn_jim.jpg`.
If the pattern given to `-o` If the pattern given to `-o` is an absolute path, any path components are
is an absolute path, any path components are dropped from the input dropped from the input filenames. This lets you write all of your thumbnails
filenames. This lets you write all of your thumbnails to a specific to a specific directory, if you want. For example:
directory, if you want. For example:
``` ```
$ vipsthumbnail fred.jpg ../jim.tif -o /mythumbs/tn_%s.jpg $ vipsthumbnail fred.jpg ../jim.tif -o /mythumbs/tn_%s.jpg
``` ```
Now both thumbnails will be written to `/mythumbs`, Now both thumbnails will be written to `/mythumbs`, even though the source
even though the source images are in different directories. images are in different directories.
Conversely, if `-o` Conversely, if `-o` is set to a relative path, any path component from the
is set to a relative path, any path component from the input file is input file is prepended. For example:
prepended. For example:
``` ```
$ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg
@ -149,8 +175,7 @@ their current directory.
# Output format and options # Output format and options
You can use `-o` You can use `-o` to specify the thumbnail image format too. For example: 
to specify the thumbnail image format too. For example: 
``` ```
$ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png
@ -158,18 +183,17 @@ $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png
Will write thumbnails in PNG format. Will write thumbnails in PNG format.
You can give options to the image write operation as a list of You can give options to the image write operation as a list of comma-separated
comma-separated arguments in square brackets. For example: arguments in square brackets. For example:
``` ```
$ 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]
``` ```
will write jpeg images with quality 90, and will turn on the libjpeg will write jpeg images with quality 90, and will turn on the libjpeg coding
coding optimizer. optimizer.
Check the image write operations to see all the possible options. For Check the image write operations to see all the possible options. For example:
example:
``` ```
$ vips jpegsave $ vips jpegsave

85
doc/Using-vipsthumbnail.xml
View File

@ -3,25 +3,25 @@
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="Using-vipsthumbnail.md"> <refentry id="Using-vipsthumbnail.md">
<refmeta>
<refentrytitle>Using-vipsthumbnail.md</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libvips</refname>
<refpurpose>Using-vipsthumbnail.md</refpurpose>
</refnamediv>
<para> <para>
libvips ships with a handy command-line image thumbnailer, <literal>vipsthumbnail</literal>. This page introduces it with examples. <refmeta> <refentrytitle>Using <literal>vipsthumbnail</literal></refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>libvips</refmiscinfo> </refmeta>
</para> </para>
<para> <para>
The thumbnailing functionality is implemeted by <literal>vips_thumbnail()</literal> and <literal>vips_thumbnail_buffer()</literal>, see the docs for details. You can use these functions from any language with a libvips binding. <refnamediv> <refname><literal>vipsthumbnail</literal></refname> <refpurpose>Introduction to <literal>vipsthumbnail</literal>, with examples</refpurpose> </refnamediv>
</para> </para>
<refsect2 id="libvips-options"> <para>
libvips ships with a handy command-line image thumbnailer, <literal>vipsthumbnail</literal>. This page introduces it, with some examples.
</para>
<para>
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:
</para>
<programlisting language="php">
$filename = ...;
$image = Vips\Image::thumbnail($filename, 200, [&quot;height&quot; =&gt; 200]);
$image.writeToFile(&quot;my-thumbnail.jpg&quot;);
</programlisting>
<refsect3 id="libvips-options">
<title>libvips options</title> <title>libvips options</title>
<para> <para>
<literal>vipsthumbnail</literal> supports the usual range of vips command-line options. A few of them are useful: <literal>vipsthumbnail</literal> supports the usual range of vips command-line options. A few of them are useful:
@ -38,17 +38,17 @@
<para> <para>
<literal>--vips-info</literal> shows a higher level view of the operations that <literal>vipsthumbnail</literal> is running.  <literal>--vips-info</literal> shows a higher level view of the operations that <literal>vipsthumbnail</literal> is running. 
</para> </para>
</refsect2> </refsect3>
<refsect2 id="looping"> <refsect3 id="looping">
<title>Looping</title> <title>Looping</title>
<para> <para>
vipsthumbnail can process many images in one operation. For example: <literal>vipsthumbnail</literal> can process many images in one command. For example:
</para> </para>
<programlisting> <programlisting>
$ vipsthumbnail *.jpg $ vipsthumbnail *.jpg
</programlisting> </programlisting>
<para> <para>
will make a thumbnail for every jpeg in the current directory.  See the <emphasis role="strong">Output directory</emphasis> section below to see how to change where thumbnails are written. will make a thumbnail for every jpeg in the current directory.  See the <link linkend="output-directory">Output directory</link> section below to see how to change where thumbnails are written.
</para> </para>
<para> <para>
<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> 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:
@ -56,8 +56,8 @@ $ vipsthumbnail *.jpg
<programlisting> <programlisting>
$ parallel vipsthumbnail ::: *.jpg $ parallel vipsthumbnail ::: *.jpg
</programlisting> </programlisting>
</refsect2> </refsect3>
<refsect2 id="thumbnail-size"> <refsect3 id="thumbnail-size">
<title>Thumbnail size</title> <title>Thumbnail size</title>
<para> <para>
You can set the bounding box of the generated thumbnail with the <literal>--size</literal> option. For example: You can set the bounding box of the generated thumbnail with the <literal>--size</literal> option. For example:
@ -77,8 +77,8 @@ $ vipsthumbnail shark.jpg --size 200x
<para> <para>
You can append <literal>&lt;</literal> or <literal>&gt;</literal> to mean only resize if the image is smaller or larger than the target. You can append <literal>&lt;</literal> or <literal>&gt;</literal> to mean only resize if the image is smaller or larger than the target.
</para> </para>
</refsect2> </refsect3>
<refsect2 id="cropping"> <refsect3 id="cropping">
<title>Cropping</title> <title>Cropping</title>
<para> <para>
<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: <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:
@ -111,8 +111,8 @@ $ vipsthumbnail owl.jpg --smartcrop attention -s 128
<para> <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. 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.
</para> </para>
</refsect2> </refsect3>
<refsect2 id="linear-light"> <refsect3 id="linear-light">
<title>Linear light</title> <title>Linear light</title>
<para> <para>
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 a CRT electron gun. 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 a CRT electron gun.
@ -124,10 +124,23 @@ $ vipsthumbnail owl.jpg --smartcrop attention -s 128
$ vipsthumbnail fred.jpg --linear $ vipsthumbnail fred.jpg --linear
</programlisting> </programlisting>
<para> <para>
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 done by the image libraries is done at encode time, and done in terms of CRT voltage, not light. This can make linear light thumbnailing of large images extremely slow. 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>
</refsect2> <para>
<refsect2 id="output-directory"> For example, for a 10,000 x 10,000 pixel JPEG I see:
</para>
<programlisting>
$ time vipsthumbnail wtc.jpg
real 0m0.317s
user 0m0.292s
sys 0m0.016s
$ time vipsthumbnail wtc.jpg --linear
real 0m4.660s
user 0m4.640s
sys 0m0.016s
</programlisting>
</refsect3>
<refsect3 id="output-directory">
<title>Output directory</title> <title>Output directory</title>
<para> <para>
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: 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:
@ -156,8 +169,8 @@ $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg
<para> <para>
Now both input files will have thumbnails written to a subdirectory of their current directory. Now both input files will have thumbnails written to a subdirectory of their current directory.
</para> </para>
</refsect2> </refsect3>
<refsect2 id="output-format-and-options"> <refsect3 id="output-format-and-options">
<title>Output format and options</title> <title>Output format and options</title>
<para> <para>
You can use <literal>-o</literal> to specify the thumbnail image format too. For example:  You can use <literal>-o</literal> to specify the thumbnail image format too. For example: 
@ -231,8 +244,8 @@ $ vipsthumbnail 42-32157534.jpg -o x.jpg[optimize_coding,strip]
$ ls -l x.jpg $ ls -l x.jpg
-rw-r–r– 1 john john 3600 Nov 12 21:27 x.jpg -rw-r–r– 1 john john 3600 Nov 12 21:27 x.jpg
</programlisting> </programlisting>
</refsect2> </refsect3>
<refsect2 id="colour-management"> <refsect3 id="colour-management">
<title>Colour management</title> <title>Colour management</title>
<para> <para>
<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. <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.
@ -259,8 +272,8 @@ $ ls -l tn_shark.jpg
<para> <para>
You can also specify a fallback input profile to use if the image has no embedded one, but this is less useful. You can also specify a fallback input profile to use if the image has no embedded one, but this is less useful.
</para> </para>
</refsect2> </refsect3>
<refsect2 id="auto-rotate"> <refsect3 id="auto-rotate">
<title>Auto-rotate</title> <title>Auto-rotate</title>
<para> <para>
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. 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.
@ -268,8 +281,8 @@ $ ls -l tn_shark.jpg
<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. 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.
</para> </para>
</refsect2> </refsect3>
<refsect2 id="final-suggestion"> <refsect3 id="final-suggestion">
<title>Final suggestion</title> <title>Final suggestion</title>
<para> <para>
Putting all this together, I suggest this as a sensible set of options: Putting all this together, I suggest this as a sensible set of options:
@ -281,7 +294,7 @@ $ vipsthumbnail fred.jpg \
--eprofile /usr/share/color/icc/sRGB.icc \ --eprofile /usr/share/color/icc/sRGB.icc \
--rotate --rotate
</programlisting> </programlisting>
</refsect2> </refsect3>
</refentry> </refentry>

11
doc/pandoc-docbook-template.docbook
View File

@ -8,17 +8,6 @@ $else$
$endif$ $endif$
<refentry id="$title$"> <refentry id="$title$">
<refmeta>
<refentrytitle>$title$</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>libvips</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libvips</refname>
<refpurpose>$title$</refpurpose>
</refnamediv>
$for(include-before)$ $for(include-before)$
$include-before$ $include-before$
$endfor$ $endfor$