libvips/doc/using-command-line.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>