libvips/doc/using-command-line.xml

232 lines
6.8 KiB
XML

<?xml version="1.0"?>
<!-- vim: set ts=2 sw=2 expandtab: -->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="using-cli">
<refmeta>
<refentrytitle>VIPS from the command-line</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>VIPS Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Using VIPS</refname>
<refpurpose>How to use the VIPS library from the command-line</refpurpose>
</refnamediv>
<refsect3 id="using-command-line-intro">
<title>Introduction</title>
<para>
Use the <command>vips</command> command to execute VIPS operations from
the command-line. For example:
<programlisting>
$ vips rot k2.jpg x.jpg d90
</programlisting>
Will rotate the image <literal>k2.jpg</literal> by 90 degrees
anticlockwise and write the result to the file <literal>x.jpg</literal>.
If you don't give any arguments to an operation,
<command>vips</command> will give a short description, for example:
<programlisting>
$ vips rot
rotate an image
usage:
rot in out angle
where:
in - Input image, input VipsImage
out - Output image, output VipsImage
angle - Angle to rotate image, input VipsAngle
default: d90
allowed: d0, d90, d180, d270
</programlisting>
There's a straightforward relationship with the C API: compare this to
the API docs for vips_rot(), for example.
</para>
</refsect3>
<refsect3 id="using-command-line-list">
<title>Listing all operations</title>
<para>
You can list all classes with:
<programlisting>
$ vips -l
...
VipsOperation (operation), operations
VipsSystem (system), run an external command
VipsArithmetic (arithmetic), arithmetic operations
VipsBinary (binary), binary operations
VipsAdd (add), add two images
... etc.
</programlisting>
Each line shows the canonical name of the class (for example
<literal>VipsAdd</literal>), the class nickname
(<literal>add</literal> in this case), and a short description.
Some subclasses of operation will show more: for example, subclasses of
<literal>VipsForeign</literal> will show some of the extra flags
supported by the file load/save operations.
</para>
</refsect3>
<refsect3 id="using-command-line-options">
<title>Optional arguments</title>
<para>
Many operations take optional arguments. You can supply these as
command-line options, for example:
<programlisting>
$ vips gamma
gamma an image
usage:
gamma in out
where:
in - Input image, input VipsImage
out - Output image, output VipsImage
optional arguments:
exponent - Gamma factor, input gdouble
default: 2.4
min: 1e-06, max: 1000
operation flags: sequential-unbuffered
</programlisting>
vips_gamma() applies a gamma factor to an image. By
default, it uses 2.4, the sRGB gamma factor, but you can specify any
gamma with the <literal>exponent</literal> option.
</para>
<para>
Use it from the command-line like this:
<programlisting>
$ vips gamma k2.jpg x.jpg --exponent 0.42
</programlisting>
This will read file <literal>k2.jpg</literal>, un-gamma it, and
write the result to file <literal>x.jpg</literal>.
</para>
</refsect3>
<refsect3 id="using-command-line-array">
<title>Array arguments</title>
<para>
Some operations take arrays of values as arguments, for example,
vips_affine() needs an array of four numbers for the
2x2 transform matrix. You pass arrays as space-separated lists, for
example:
<programlisting>
$ vips affine k2.jpg x.jpg "2 0 0 1"
</programlisting>
You may need the quotes to stop your shell breaking the argument at
the spaces. vips_bandjoin() needs an array of input images to
join, run it like this:
<programlisting>
$ vips bandjoin "k2.jpg k4.jpg" x.tif
</programlisting>
</para>
</refsect3>
<refsect3 id="using-command-line-conversion">
<title>Implicit file format conversion</title>
<para>
<command>vips</command> will automatically convert between image file
formats for you. Input images are detected by sniffing their first few
bytes; output formats are set from the filename suffix. You can see a
list of all the supported file formats with something like:
<programlisting>
$ vips -l foreign
</programlisting>
Then get a list of the options a format supports with, for example:
<programlisting>
$ vips jpegsave
</programlisting>
</para>
<para>
You can pass options to the implicit load and save operations enclosed
in square brackets after the filename. For example:
<programlisting>
vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"
</programlisting>
Will write <literal>x.jpg</literal> at quality level 90 and will
strip all metadata from the image.
</para>
</refsect3>
<refsect3 id="using-command-line-chaining">
<title>Chaining operations</title>
<para>
Because each operation runs in a separate process, you can't use
libvips's chaining system to join operations together, you have to use
intermediate files. The command-line interface is therefore quite a bit
slower than Python or C.
</para>
<para>
The best alternative is to use vips files for intermediates.
Something like:
<programlisting>
vips invert input.jpg t1.v
vips affine t1.v output.jpg "2 0 0 1"
rm t1.v
</programlisting>
</para>
</refsect3>
<refsect3 id="using-command-line-other">
<title>Other features</title>
<para>
Finally, <command>vips</command> has a couple of useful extra options.
<itemizedlist>
<listitem>
<para>
Use <option>--vips-progress</option> to get
<command>vips</command> to display a simple progress indicator.
</para>
</listitem>
<listitem>
<para>
Use <option>--vips-leak</option> and <command>vips</command> will
leak-test on exit, and also display an estimate of peak memory use.
</para>
</listitem>
<listitem>
<para>
Set <code>G_MESSAGES_DEBUG=VIPS</code> and GLib will display
informational and debug messages from libvips.
</para>
</listitem>
</itemizedlist>
</para>
<para>
VIPS comes with a couple of other useful programs.
<command>vipsheader</command> is a command which can print image header
fields. <command>vipsedit</command> can change fields in vips format
images. <command>vipsthumbnail</command> can make image thumbnails
quickly.
</para>
</refsect3>
</refentry>