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

rewrite vips-cli docs

Browse Source 
clearer and better formatting
This commit is contained in:
John Cupitt 2015-01-28 09:50:15 +00:00
parent e8f456a7e2
commit ecf10f85a1
1 changed files with 108 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
doc/reference/using-command-line.xml
View File

@ -15,113 +15,160 @@
<refpurpose>How to use the VIPS library from the command-line</refpurpose>
</refnamediv>
<refsect1 id="using-command-line">
<title>Using VIPS from the command-line</title>
<refsect1 id="using-command-line-intro">
<title>Introduction</title>
<para>
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>
<userinput>vips list classes</userinput>
</literallayout>
<programlisting>
$ vips rot k2.jpg x.jpg d90
</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>
<userinput>VipsOperation (operation), operations</userinput>
<userinput> VipsSystem (system), run an external command</userinput>
<userinput> VipsArithmetic (arithmetic), arithmetic operations</userinput>
<userinput> VipsBinary (binary), binary operations</userinput>
<userinput> VipsAdd (add), add two images</userinput>
<userinput> .... and so on</userinput>
</literallayout>
<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>
</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
<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
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>
</refsect1>
You can get help on a specific operation by running it with no arguments,
for example:
<refsect1 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:
<literallayout>
<userinput>vips gamma</userinput>
</literallayout>
<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>
produces the output:
<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
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. You can use the
C API docs for <function>vips_gamma()</function> if you need more
information.
gamma with the <literal>exponent</literal> option.
</para>
<para>
Use it from the command-line like this:
<literallayout>
<userinput>vips gamma k2.jpg x.jpg --exponent 0.42</userinput>
</literallayout>
<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>
</refsect1>
<refsect1 id="using-command-line-array">
<title>Array arguments</title>
<para>
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
example:
<literallayout>
<userinput>vips affine k2.jpg x.jpg "2 0 0 1"</userinput>
</literallayout>
<programlisting>
$ vips affine k2.jpg x.jpg "2 0 0 1"
</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:
<literallayout>
<userinput>vips bandjoin "k2.jpg k4.jpg" x.tif</userinput>
</literallayout>
<programlisting>
$ vips bandjoin "k2.jpg k4.jpg" x.tif
</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
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:
<literallayout>
<userinput>vips list classes | grep -i foreign</userinput>
</literallayout>
<programlisting>
$ vips list classes | grep -i foreign
</programlisting>
Then get a list of the options a format supports with, for example:
<literallayout>
<userinput>vips jpegsave</userinput>
</literallayout>
<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:
<literallayout>
<userinput>vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"</userinput>
</literallayout>
<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>
</refsect1>
<refsect1 id="using-command-line-other">
<title>Other features</title>
<para>
Finally, <command>vips</command> has a couple of useful extra options.
<itemizedlist>
@ -147,7 +194,6 @@
fields. <command>vipsedit</command> can change fields in vips format
images. <command>vipsthumbnail</command> can make image thumbnails
quickly.
</para>
</refsect1>