rewrite vips-cli docs

clearer and better formatting
This commit is contained in:
John Cupitt 2015-01-28 09:50:15 +00:00
parent e8f456a7e2
commit ecf10f85a1

View File

@ -15,113 +15,160 @@
<refpurpose>How to use the VIPS library from the command-line</refpurpose> <refpurpose>How to use the VIPS library from the command-line</refpurpose>
</refnamediv> </refnamediv>
<refsect1 id="using-command-line"> <refsect1 id="using-command-line-intro">
<title>Using VIPS from the command-line</title> <title>Introduction</title>
<para> <para>
Use the <command>vips</command> command to execute VIPS operations from Use the <command>vips</command> command to execute VIPS operations from
the command-line. You can show all classes with: the command-line. For example:
<literallayout> <programlisting>
<userinput>vips list classes</userinput> $ vips rot k2.jpg x.jpg d90
</literallayout> </programlisting>
This produces output something like: 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:
<literallayout> <programlisting>
<userinput>VipsOperation (operation), operations</userinput> $ vips rot
<userinput> VipsSystem (system), run an external command</userinput> rotate an image
<userinput> VipsArithmetic (arithmetic), arithmetic operations</userinput> usage:
<userinput> VipsBinary (binary), binary operations</userinput> rot in out angle
<userinput> VipsAdd (add), add two images</userinput> where:
<userinput> .... and so on</userinput> in - Input image, input VipsImage
</literallayout> 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>
</refsect1>
<refsect1 id="using-command-line-list">
<title>Listing all operations</title>
<para>
You can list all classes with:
<programlisting>
$ vips list classes
...
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 Each line shows the canonical name of the class (for example
<literal>VipsAdd</literal>), the class nickname <literal>VipsAdd</literal>), the class nickname
(<literal>add</literal> in this case), and a short description. (<literal>add</literal> in this case), and a short description.
Some subclasses of operation will show more, for example subclasses of Some subclasses of operation will show more: for example, subclasses of
<literal>VipsForeign</literal> will show some of the extra flags <literal>VipsForeign</literal> will show some of the extra flags
supported by the file load/save operations. supported by the file load/save operations.
</para>
</refsect1>
You can get help on a specific operation by running it with no arguments, <refsect1 id="using-command-line-options">
for example: <title>Optional arguments</title>
<para>
Many operations take optional arguments. You can supply these as
command-line options, for example:
<literallayout> <programlisting>
<userinput>vips gamma</userinput> $ vips gamma
</literallayout> 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>
produces the output: vips_gamma() applies a gamma factor to an image. By
<literallayout>
<userinput>gamma an image</userinput>
<userinput>usage:</userinput>
<userinput> gamma in out</userinput>
<userinput>where:</userinput>
<userinput> in - Input image, input VipsImage</userinput>
<userinput> out - Output image, output VipsImage</userinput>
<userinput>optional arguments:</userinput>
<userinput> exponent - Gamma factor, input gdouble</userinput>
<userinput> default: 2.4 </userinput>
<userinput> min: 1e-06, max: 1000 </userinput>
<userinput>operation flags: sequential-unbuffered</userinput>
</literallayout>
<command>vips gamma</command> applies a gamma factor to an image. By
default, it uses 2.4, the sRGB gamma factor, but you can specify any default, it uses 2.4, the sRGB gamma factor, but you can specify any
gamma with the <literal>exponent</literal> option. You can use the gamma with the <literal>exponent</literal> option.
C API docs for <function>vips_gamma()</function> if you need more </para>
information.
<para>
Use it from the command-line like this: Use it from the command-line like this:
<literallayout> <programlisting>
<userinput>vips gamma k2.jpg x.jpg --exponent 0.42</userinput> $ vips gamma k2.jpg x.jpg --exponent 0.42
</literallayout> </programlisting>
This will read file <literal>k2.jpg</literal>, un-gamma it, and This will read file <literal>k2.jpg</literal>, un-gamma it, and
write the result to file <literal>x.jpg</literal>. write the result to file <literal>x.jpg</literal>.
</para>
</refsect1>
<refsect1 id="using-command-line-array">
<title>Array arguments</title>
<para>
Some operations take arrays of values as arguments, for example, Some operations take arrays of values as arguments, for example,
<command>vips affine</command> needs an array of four numbers for the vips_affine() needs an array of four numbers for the
2x2 transform matrix. You pass arrays as space-separated lists, for 2x2 transform matrix. You pass arrays as space-separated lists, for
example: example:
<literallayout> <programlisting>
<userinput>vips affine k2.jpg x.jpg "2 0 0 1"</userinput> $ vips affine k2.jpg x.jpg "2 0 0 1"
</literallayout> </programlisting>
Or <command>vips bandjoin</command> needs an array of input images to 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: join, run it like this:
<literallayout> <programlisting>
<userinput>vips bandjoin "k2.jpg k4.jpg" x.tif</userinput> $ vips bandjoin "k2.jpg k4.jpg" x.tif
</literallayout> </programlisting>
</para>
</refsect1>
<refsect1 id="using-command-line-conversion">
<title>Implicit file format conversion</title>
<para>
<command>vips</command> will automatically convert between image file <command>vips</command> will automatically convert between image file
formats for you. Input images are detected by sniffing their first few 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 bytes; output formats are set from the filename suffix. You can see a
list of all the supported file formats with something like: list of all the supported file formats with something like:
<literallayout> <programlisting>
<userinput>vips list classes | grep -i foreign</userinput> $ vips list classes | grep -i foreign
</literallayout> </programlisting>
Then get a list of the options a format supports with, for example: Then get a list of the options a format supports with, for example:
<literallayout> <programlisting>
<userinput>vips jpegsave</userinput> $ vips jpegsave
</literallayout> </programlisting>
</para>
<para>
You can pass options to the implicit load and save operations enclosed You can pass options to the implicit load and save operations enclosed
in square brackets after the filename. For example: in square brackets after the filename. For example:
<literallayout> <programlisting>
<userinput>vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"</userinput> vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"
</literallayout> </programlisting>
Will write <literal>x.jpg</literal> at quality level 90 and will Will write <literal>x.jpg</literal> at quality level 90 and will
strip all metadata from the image. strip all metadata from the image.
</para>
</refsect1>
<refsect1 id="using-command-line-other">
<title>Other features</title>
<para>
Finally, <command>vips</command> has a couple of useful extra options. Finally, <command>vips</command> has a couple of useful extra options.
<itemizedlist> <itemizedlist>
@ -147,7 +194,6 @@
fields. <command>vipsedit</command> can change fields in vips format fields. <command>vipsedit</command> can change fields in vips format
images. <command>vipsthumbnail</command> can make image thumbnails images. <command>vipsthumbnail</command> can make image thumbnails
quickly. quickly.
</para> </para>
</refsect1> </refsect1>