|
cqcam - program to capture color QuickCam images
xcqcam - cqcam with added X11 functionality
webcam - cqcam with streaming-JPEG output
TABLE OF CONTENTS
SYNOPSIS
cqcam [-32[+|-]] [-a[+|-]] [-b brightness] [-B level] [-c contrast] [-d
mode] [-H hue] [-j] [-l left] [-P port] [-q] [-r] [-s scale] [-S saturation] [-t top] [-w
level] [-u] [-x width] [-y height]
cqcam -h
xcqcam [-32[+|-]] [-a[+|-]] [-b brightness] [-B level] [-c contrast] [-d mode]
[-display host:display] [-H hue] [-l left] [-p[+|-]] [-P port] [-s scale] [-S saturation]
[-t top] [-w level] [-u] [-x width] [-y height]
xcqcam -h
webcam [-32[+|-]] [-a[+|-]] [-b brightness] [-B level] [-c contrast] [-d mode]
[-H hue] [-l left] [-L frames] [-P port] [-q] [-r] [-s scale] [-S saturation] [-t top] [-w
level] [-u] [-x width] [-y height]
webcam -h
DESCRIPTION
cqcam captures images from a parallel-port color QuickCam and optionally adjusts
their brightness and color and despeckles them. Output is on stdout, in PPM or JPEG
format.
xcqcam captures images from a parallel-port color QuickCam and displays them to
an X11 window, using shared memory if it is available. The color-adjustment and
despeckling tools are available via a remote control if you have xview or Tcl/Tk. Output
is to a file, in PPM format.
webcam captures images from a parallel-port color QuickCam and optionally
adjusts their brightness and color and despeckles them. Output is a set number of frames
in the form of an JPEG image stream.
OPTIONS
-32[+|-]
Use 32bpp (+) or 24bpp (-) mode for transfers. -32 alone uses the behavior opposite
the compiled-in default (usually, this results in 24bpp transfers). 32bpp mode will result
in pictures that are far faster but slightly lower in quality.
-a[+|-]
Use (+) or suppress (\-) initial brightness and color balance auto-adjustments. -a
alone uses the behavior opposite the compiled-in default (usually, this results in
suppressing adjustment). Using -a with xcqcam affects only the inital adjustments;
if the remote control is enabled, its "Adjust" button will still work.
-b brightness
Set scan brightness. Use high values for low light. Valid values: 0-254.
-B black level
Set the black level of the scan. The black level determines the amount of black in the
image. The default value will usually be fine. Valid values: 0-255.
-c contrast
Set scan contrast. Contrast determines the range of difference between light and dark
pixels. It should almost always be left at its default. Valid values: 0-254.
-d mode
Set the camera-detection mode. mode can be any integer from 0 to 4, where 0 is no
detection and 4 is maximum detection. 1 is usually the compiled-in default and should be
sufficient.
-display host:display
(xcqcam only) Set an X display other than the $DISPLAY variable.
-h
View a brief readout of available options.
-H hue
Set the hue (blue level) of the scan. The default value is usually fine. Valid values:
0-255.
-j (cqcam only) Output is in JPEG format instead of the default
PPM format. This option may not be available if you chose not to use libjpeg at compile
time.
-l column
Set the left column of the scan. Since the first 10 logical columns are black (reference)
pixels, this value should be at least 11. Valid values: 0-320.
-L frames
(webcam only) Set the maximum number of JPEG frames to send on the stdout stream.
The client may halt the stream prematurely by hitting the "stop" button in
his/her browser. This is 20 by default.
-p[+|-]
(xcqcam only) Use (+) or suppress (-) a private colormap on 8-bpp displays. -p
alone uses the behavior opposite the compiled-in default (usually, this results in a
standard, non-private colormap).
-P port
Set port to attempt. The value must be in hexadecimal format, without the leading 0x. For
example, -P 3bc. This can cause really unpredictable results (possibly hardware
lockups) if it is set to the wrong values; thus, only root may use -P. Specifying a
port of 0 causes the program to probe 0x378, 0x278, and 0x3bc; this is usually the
compiled-in default.
-q quality
(cqcam only) Set the output quality for JPEG images. This option has no effect if -j
is not used. Valid values are 1 to 100; the default is 50.
-r
(cqcam only) After cqcam is finished auto-adjusting brightness, force it to store
the calculated brightness in the config file. This way, brightness adjustments should be
much quicker the next time. This is good for when you have to take many pictures of the
same thing and you don't expect the light level to change much. (See Frame Rates, below)
-s scale factor
Set the decimation of the scan. For example, using a value of 4 takes only every fourth
horizontal and vertical pixel (4:1 decimation), which decreases the transfer time by a
factor of 16. Acceptable values are 1, 2, and 4.
-S saturation
Set the saturation of the scan. The saturation determines the strength of the colors. Too
high a saturation (especially with flourescent lighting) causes severe bleeding of colors.
Valid values: 0-255.
-t row
Set the top row of the scan. This is usually set to 1. Valid values: 1-240.
-u
Force uni-directional mode. It's possible that a port may be detected as a bi-directional
port but not function correctly as one. If this is the case, the application will probably
freeze as soon as it goes to fetch video data, and forcing uni-directional mode is worth a
try.
-w white level
Set the white level of the scan. The white level determines the amount of white in the
image. The default value will usually be fine. Valid values: 0-255.
-x width
Set scan width, in pixels. Valid values in 24bpp mode: 4-320. Valid values in 32bpp mode:
4-640.
-y height
Set scan height, in pixels. Valid values in 24bpp mode: 4-240. Valid values in 32bpp mode:
4-480.
IMAGE SIZES
The image size is determined by the -x, -y, and -s flags. The
image will be the width and height specified, divided by the decimation specified.
Note: -x 320 -y 240 -s 2 is not the same as -x 160 -y 120 -s 1. The
latter is more "zoomed in." (Connectix refers to this as "electronic
zoom.")
Specifying 32bpp transfer mode (-32[+|-]) has no effect on image size, except
that in 24bpp mode the maximum size is 320x240, and in 32bpp mode the maximum size is
640x480.
A related FAQ: what is the difference between 24bpp and 32bpp transfers, and why aren't
24bpp transfers faster?
Answer: 24bpp transfers blocks of 24 bits (8 bits each of red, green, and blue) from
which one pixel is constructed. 32bpp transfers blocks of 32 bits (8 of red, 16 of green,
and 8 of blue) from which four pixels are constructed, at a slight loss of quality.
Trivial arithmetic says that the same image will come through three times as quickly with
32bpp, though reality says that the image will be a bit blurrier.
FRAME RATES
How to improve your frame rate, in rough order of priority:
Bidirectional ports
Use jumpers or BIOS settings to make your parallel port bidirectional, or buy a new
parallel port. EPP or SPP-bidirectional modes are recommended; ECP mode is not.
Bidirectional ports triple the frame rate.
32bpp transfers
Using 32bpp transfers (-32+, which is probably the default) triples the frame
rate.
Image size and decimation
Transfer times are, unsurprisingly, directly proportional to image area. Shrinking your
image will speed up frame rates.
Brightness and exposure time
With very poor lighting, the exposure time may be the limiting factor for the frame
rate. Try increasing the available light, if possible, until the brightness is less than
160.
Auto-adjustment (cqcam only)
cqcam attempts to auto-detect the ideal brightness level every time it runs. It does
this by taking successive pictures (up to 10!) and making adjustments until the image
quality is acceptable.
You can turn off auto-adjustment to speed up image captures. Here's how:
- Run cqcam (not xcqcam) once with -a+ -r (adjustments on, "remember" the
brightness)
- After that, you can run either cqcam or xcqcam with -a- (adjustments off) until
the light level changes significantly and it will reuse whatever optimal value it has
already figured out.
- When the light level changes significantly, go to step 1. The software can correct small
changes in lighting, but if the light changes too much, your images will look washed-out.
If you are using cqcam as a webcam, try using -a+ -r every couple of hours and -a-
all of the other times.
IMAGE QUALITY
Factors that affect image quality:
Transfer times
Speeding up transfer times (see above) will improve image consistancy. Images that are
too large or too slow may have severe color-bleed toward the bottom.
System load
If other processes are running while the camera is transferring a picture, image
quality will be severely worsened. cqcam should run with the highest possible priority.
32bpp transfers
32bpp transfers use a sort of "image reconstruction" technique to quadruple
the effective size of a QuickCam image; I use this to increase transfer rates.
The increased transfer rates will improve image consistency, but the image
reconstruction is lossy, so the images will be slightly less clear.
XCQCAM INTERFACE
If xcqcam was compiled with the remote control enabled (this is the default, and it
requires openlook/xview), a second window will appear when xcqcam is run.
Eight functions be made through this window:
Adjust
Automatically adjust brightness (shutter speed) and color levels to bring the image to
normal light/hue levels. This process usually takes 3-5 frames to complete.
Take picture
Take a picture. A prompt will appear on stdin asking for the filename. All operations
will be suspended until one is entered.
Brightness
Set the image brightness (corresponds to -b, above). This can usually be set
automatically using the "Adjust" button.
Black level
Set the camera's black level (corresponds to -B, above).
White level
Set the camera's white level (corresponds to -w, above).
Red level
Green level
Blue level
Set the amount of red, green, and blue in the image. This is a software adjustment, not
part of the camera itself. They can usually be set automatically using the
"Adjust" button. The range 1-254 corresponds to 1% to 200% amplification of the
given color.
RESOURCES
cqcam requires a color QuickCam on a parallel port.
xcqcam requires everything cqcam does, plus an X11 display. The shared memory (SHM)
extension is recommended; use the -m switch if SHM is not available. Compiling the remote
control extension (highly recommended) requires the xview (by default) or Tcl/Tk include
files and libraries.
xview is available (in compiled package form) from any ftp site that mirrors Slackware,
as the XV diskset. The SHM extension should be available with all recent versions of
XFree86. Tcl/Tk is also available from Slackware.
SEE ALSO
There are no related man pages that I know of.
See README, CHANGES, and TODO for information regarding the code.
See Makefile and config.h for options that can be specified at compile time. (Most of
these can be overridden at run time.)
See the source itself for extremely specific information and occasionally useful
comments. If you want the details of the API, write to me to ask for them: patrickr@virginia.edu.
http://www.quickcam.com/developer.html
- The Connectix QuickCam developers' program.
COPYRIGHT
cqcam and xcqcam are Copyright © 1996-1997 Patrick Reynolds.
This is freeware, but please get my permission before putting it in any distributions
of any kind.
See the file COPYING for details.
BUGS
None?
Please see TODO for non-bug things that I want to change.
To submit a bug report, please enable -DDEBUG in the Makefile, recompile the package
with 'make clean all', and send the output, along with what you consider to be relevent
details, to: Patrick Reynolds <patrickr@virginia.edu>
AUTHORS
Primary author
Patrick Reynolds <patrickr@virginia.edu>
Contributors
Philip Blundell <philip.blundell@pobox.com>
Anders Arpteg <aa11ac@hik.se>
Ciaran Carter <ciaran.carter@stbrn.ac.uk>
Charles Henrich <henrich@crh.cl.msu.edu>
Andre Jesmanowicz <andre@andrix.biophysics.mcw.edu>
Joe Ilacqua <spike@indra.com>
Fabio Fregi and Giuseppe Guerrini <cni@bo.nettuno.it>
Shawn Stepper <stepper@vip.stanford.edu>
Håkan Lennestål <Hakan.Lennestal@cdt.luth.se>
|Back to my webcam page|
|