diff --git a/doc/reference/using-command-line.xml b/doc/reference/using-command-line.xml
index 9377c9cc..1cb49237 100644
--- a/doc/reference/using-command-line.xml
+++ b/doc/reference/using-command-line.xml
@@ -15,113 +15,160 @@
How to use the VIPS library from the command-line
-
- Using VIPS from the command-line
+
+ Introduction
Use the vips command to execute VIPS operations from
- the command-line. You can show all classes with:
+ the command-line. For example:
-
- vips list classes
-
+
+$ vips rot k2.jpg x.jpg d90
+
- This produces output something like:
+ Will rotate the image k2.jpg by 90 degrees
+ anticlockwise and write the result to the file x.jpg.
+ If you don't give any arguments to an operation,
+ vips will give a short description, for example:
-
- VipsOperation (operation), operations
- VipsSystem (system), run an external command
- VipsArithmetic (arithmetic), arithmetic operations
- VipsBinary (binary), binary operations
- VipsAdd (add), add two images
- .... and so on
-
+
+$ 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
+
+
+ There's a straightforward relationship with the C API: compare this to
+ the API docs for vips_rot(), for example.
+
+
+
+
+ Listing all operations
+
+ You can list all classes with:
+
+
+$ 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.
+
Each line shows the canonical name of the class (for example
VipsAdd), the class nickname
(add 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
VipsForeign will show some of the extra flags
supported by the file load/save operations.
+
+
- You can get help on a specific operation by running it with no arguments,
- for example:
+
+ Optional arguments
+
+ Many operations take optional arguments. You can supply these as
+ command-line options, for example:
-
- vips gamma
-
+
+$ 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
+
- produces the output:
-
-
- 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
-
-
- vips gamma 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 exponent option. You can use the
- C API docs for vips_gamma() if you need more
- information.
+ gamma with the exponent option.
+
+
Use it from the command-line like this:
-
- vips gamma k2.jpg x.jpg --exponent 0.42
-
+
+$ vips gamma k2.jpg x.jpg --exponent 0.42
+
This will read file k2.jpg, un-gamma it, and
write the result to file x.jpg.
+
+
+
+ Array arguments
+
Some operations take arrays of values as arguments, for example,
- vips affine 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:
-
- vips affine k2.jpg x.jpg "2 0 0 1"
-
+
+$ vips affine k2.jpg x.jpg "2 0 0 1"
+
- Or vips bandjoin 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:
-
- vips bandjoin "k2.jpg k4.jpg" x.tif
-
+
+$ vips bandjoin "k2.jpg k4.jpg" x.tif
+
+
+
+
+ Implicit file format conversion
+
vips 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:
-
- vips list classes | grep -i foreign
-
+
+$ vips list classes | grep -i foreign
+
Then get a list of the options a format supports with, for example:
-
- vips jpegsave
-
+
+$ vips jpegsave
+
+
+
You can pass options to the implicit load and save operations enclosed
in square brackets after the filename. For example:
-
- vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"
-
+
+vips affine k2.jpg x.jpg[Q=90,strip] "2 0 0 1"
+
Will write x.jpg at quality level 90 and will
strip all metadata from the image.
+
+
+
+ Other features
+
+
Finally, vips has a couple of useful extra options.
@@ -147,7 +194,6 @@
fields. vipsedit can change fields in vips format
images. vipsthumbnail can make image thumbnails
quickly.
-