237 lines
6.9 KiB
XML
237 lines
6.9 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().
|
|
</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>
|
|
|
|
<para>
|
|
The API docs have a <link linkend="function-list">handy table of all vips
|
|
operations</link>, if you want to find out how to do something, try
|
|
searching that.
|
|
</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:
|
|
|
|
<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:
|
|
|
|
<programlisting>
|
|
$ vips jpegsave
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
You can pass options to the implicit load and save operations enclosed
|
|
in square brackets after the filename:
|
|
|
|
<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>
|