rewrite vips-cli docs
clearer and better formatting
This commit is contained in:
parent
e8f456a7e2
commit
ecf10f85a1
@ -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>
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user