.TH wcggrabber 1 "@DATE@" "@VERSION@" "WebCam Go image grabber"
.SH NAME
wcggrabber \- grab (capture) a frame from a video4linux (version 1) device
.SH SYNOPSIS
.B wcggrabber [OPTION]...
.SH DESCRIPTION
.B wcggrabber
grabs one frame from a video4linux (version 1) device and writes it as
an image in
.BR ppm (5)
or
.BR pgm (5)
format to standard output. The video4linux device can be specified via an
option, the default device is
.IR /dev/video0 .
If the device is set to a not supported colour space (palette),
.B wcggrabber
tries to set one of the supported palettes. Image parameters can be
controlled via options, otherwise the current device settings are used.
.SH "SUPPORTED PALETTES"
.B wcggrabber
supports the following palettes:
.IP \(bu
4, 6 and 8 bit
.B GREY
.IP \(bu
.B RGB32
.IP \(bu
.B RGB24
.IP \(bu
.B RGB565
.IP \(bu
.B RGB555
.IP \(bu
.B UYVY
.IP \(bu
.B YUYV
.IP \(bu
.B YUV422
.IP \(bu
.B YUV420
.IP \(bu
.B YUV422P
.IP \(bu
.B YUV411P
.IP \(bu
.B YUV420P
.IP \(bu
.B YUV410P
.P
If the video4linux device cannot work with one of the supported palettes,
.B wcggrabber
cannot convert the frame to
.BR ppm (5)
or
.BR pgm (5)
format. A frame can be captured in the raw format of the device with the
appropriate command line option.
.SH OPTIONS
.SS -h, --help
Write a help message to standard error. The default settings are shown as well.
.SS -V, --version
Write version information to standard error.
.SS -v, --verbose
Print information about the program execution to standard error.
.SS -q, --quiet
Do not print error or warning messages.
.SS -i, --info-only
Query the video4linux device capabilites, write them to standard error,
and exit.
.SS -s, --set-only
Set the video4linux device parameters given on the command line, and exit.
.SS -f, --file, -o, --out-file FILE
Write the image data to the specified
.B FILE
instead of standard output. You can use
.B -
to specify standard output.
.SS -d, --device DEVICE
Use the specified video4linux
.B DEVICE
instead of the default
.IR /dev/video0 .
.SS -S, --size { WIDTHxHEIGHT | KEYWORD }
Set the size of the captured image. The size can be specified by giving
the
.B WIDTH
and
.B HEIGHT
in pixels or by using a special
.BR KEYWORD .
Use
.B --size help
to get a list of supported keywords printed to standard error. Query the
device capabilities to get the usable range.
.SS -M, --max-size
Use the maximum supported image size of the video4linux device. This option
has been superseded by
.BR "--size max" .
.SS -I, --min-size
Use the minimum supported image size of the video4linux device. This option
has been superseded by
.BR "--size min" .
.SS -b, --brightness BRIGHTNESS
Set the brightness parameter of the video4linux device to
.BR BRIGHTNESS .
.SS -H, --hue HUE
Set the hue parameter of the video4linux device to
.BR HUE .
.SS -c, --colour COLOUR
Set the colour parameter of the video4linux device to
.BR COLOUR .
.SS -C, --contrast CONTRAST
Set the contrast parameter of the video4linux device to
.BR CONTRAST .
.SS -w, --whiteness WHITENESS
Set the whiteness parameter of the video4linux device to
.BR WHITENESS .
This parameter is relevant for the
.B GREY
palettes only.
.SS -p, --palette PALETTE
Set the palette of the video4linux device to
.BR PALETTE .
Use
.B --palette help
to get a list of keywords to be used as values for
.B PALETTE
printed to standard error.
.P
Note that any video4linux palette can be set,
but image capturing in
.BR ppm (5)
or
.BR pgm (5)
format is only possible for the supported palettes (see
.B SUPPORTED PALETTES
above). The pixel depth of the palette is set as well.
.SS -D, --depth DEPTH
Sets the pixel depth of the palette to
.BR DEPTH .
.P
Note that the pixel depth is automatically set, this option can be used
to manually override this. You are on you're own if you use this option.
This option can be useful to overwrite wrong default values.
.SS -n, --channel NUMBER
Set the channel parameter of the video4linux device to
.BR NUMBER .
Query the device capabilites to find out about the channels of your
video4linux device.
.SS -a, --auto-bright
Use the algorithm from
.B vgrabber.c
to automatically adjust the image brightness. This works with
.B RGB
palettes only and is intended for
.BR RGB24 " and " RGB32 ,
you should not expect it to be usable with
.BR RGB565 ", " RGB555 ", or " GREY
palettes.
.P
Note that some video4linux devices have an automatic brightness
adjustment that does not work well with this option.
.SS -t, --max-tries NUMBER
Set the maximum number of tries to find a suitable brightness setting with
.BR vgrabber.c 's
automatic brightness adjustment. The default value is
.BR 100 .
.SS -R, --rgb-map MAP
Map the values of red, green and blue, represented by
.BR RGB ,
to one of
.BR RGB ", " RBG ", " GRB ", " GBR ", " BGR ", or " BRG .
.P
Note that the
.B RGB24
and
.B RGB32
palettes are sometimes
.B BGR
palettes (at least they are on my
.B bttv
card) and therefore need the option
.BR "--rgb-map BGR" .
.SS -g, --swap-gb
Swap the green and blue bytes in output. This option has been superseded by
.BR "--rgb-map RBG" .
.SS -r, --swap-rb
Swap the red and blue bytes in output. This option has been superseded by
.BR "--rgb-map BGR" .
.SS -l, --ignore-lsb
Ignore the least significant bit of the 16bit value of the
.B RGB555
palette. If the colours of an image captured using this palette seem wrong,
try this option.
.SS -m, --ignore-msb
Ignore the most significant bit of the 16bit value of the
.B RGB555
palette. This is the default operation and works with my
.B bttv
card.
.SS -W, --write-raw
Write the raw video4linux data as output instead of a
.BR ppm "(5) or " pgm (5)
format image. This can be useful to get one frame from a video4linux device
that does not support any of the palettes supported by
.BR wcggrabber .
You could use
.BR dd (1)
instead, but you would have to compute the exact frame size yourself.
.SS -Y, --lum-only
Write a greyscale image in
.BR pgm (5)
format using only the Y (luma) values. This works for the YUV palettes only,
i.e.
.BR UYVY ", " YUYV ", and " YUV422 .
The result is not very good, you should use some image processing tool, e.g.
.BR netpbm "(1) or " ImageMagick (1),
to convert colour images to greyscale.
.SS -A, --wait-after-open SECONDS
Wait
.B SECONDS
after opening the video device. This gives the device some time for e.g.
automatic brightness adjustment or sensor initialization.
This option should not be needed, it is a workaround for buggy drivers.
This might help if you sometimes get just a blue (or red) image after
accesing the video device the first time.
.SS -z, --discard-frames NUMBER
Grab and discard
.B NUMBER
frames before grabbing the frame used for output or (with
.BR --auto-bright )
brightness adjustment.
Some video4linux devices change sensor settings during image grabbing.
Use this option to ignore image frames during this phase.
.SH EXAMPLES
Capture a frame from the default device using the current device settings
and use
.BR display (1)
from
.BR ImageMagick (1)
to display the image:
.P
.RS
wcggrabber | display -
.RE
.P
Query the capabilities of the video4linux device
.IR /dev/video1 :
.P
.RS
wcggrabber --info-only --device /dev/video1
.RE
.P
Set the default video4linux device
.I /dev/video0
to the maximum supported image size and the
.B RGB24
palette:
.P
.RS
wcggrabber --set-only --size max --palette rgb24
.RE
.P
Capture a frame from
.I /dev/video1
in
.B VGA
resolution using the
.B UYVY
palette and write it to the file
.IR image.ppm :
.P
.RS
wcggrabber -d /dev/video1 -S vga -p uyvy -o image.ppm
.RE
.SH BUGS
.B wcggrabber
uses the obsolete video4linux version 1
.SM API.
.P
.B wcggrabber
works on little endian systems only.
.P
The YUV to RGB conversion uses arbitrary values and does not conform to
any standard.
The RGB values do not conform to the CIE Rec. 709 gamma transfer
function as required by the
.BR ppm (5)
resp.
.BR pgm (5)
definition.
.P
Only a subset of the video4linux palettes is supported.
.P
Capturing colour images using the
.B YUV411P
palette does not always work correctly.
.P
The options to query and set device settings should be seperate programs.
.SH AUTHOR
.B wcggrabber
was written by Erik Auerswald <auerswal@unix-ag.uni-kl.de>
based on
.B vgrabber.c
written by Phil Blundell <philb@gnu.org> and
.B yuv2ppm.c
written by Scott Scriven <toykeeper@cheerful.com>.
.SH "SEE ALSO"
.BR netpbm (1),
.BR ppm (5),
.BR pgm (5),
.BR dd (1),
.BR ImageMagick (1),
.BR display (1),
.P
http://www.unix-ag.uni-kl.de/~auerswal/wcggrabber/
