CQCAM(1)

NAME
cqcam - program to capture color QuickCam images xcqcam - cqcam with added X11 functionality webcam - cqcam with streaming-JPEG output

SYNOPSIS
cqcam [-32[+|-]] [-a[+|-]] [-b brightness] [-B level] [-c contrast] [-d mode] [-E blue] [-G green] [-H hue] [-j] [-l left] [-L time] [-m delay,name[,count]] [-P port] [-q quality] [-r] [-R red] [-s scale] [-S saturation] [-t top] [-u] [-w level] [-x width] [-y height] cqcam -h xcqcam [-32[+|-]] [-a[+|-]] [-b brightness] [-B level] [-c contrast] [-d mode] [-display host:display] [-H hue] [-l left] [-m[+|-]] [-p[+|-]] [-P port] [-s scale] [-S saturation] [-t top] [-u] [-w level] [-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 quality] [-r] [-s scale] [-S saturation] [-t top] [-u] [-w level] [-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. Cqcam also supports a movie mode, in which it captures frames to a sequence of PPM or JPEG files. 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-255.

-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.

-E blue
    Set the software blue level, overriding automatic color balancing. Valid values: 64-255 (50%-199%).

-G green
    Set the software green level, overriding automatic color balancing. Valid values: 64-255 (50%-199%).

-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-160. (The camera doubles this to achieve a range of 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.

-L time
    (cqcam only) Use the camera's "bulb" mode to take an exposure longer than the ~2 seconds allowed by brightness=254. The time parameter is in seconds and may be a fractional quantity.

-m[+|-]
    (xcqcam only) Use (+) or suppress (-) the MIT shared-memory (SHM) extension for X11. Use it if you have it. The most common reason to suppress it is so that you can display images on another host.

-m delay,name[,count]
    (cqcam only) Enable movie mode. Cqcam takes one frame each delay seconds, saving them to name-N.ppm or name-N.jpg, depending on whether or not -j was specified. Cqcam stops after count frames if count is specified, or continues indefinitely otherwise. Delay may be a fractional quantity. If the camera's available frame rate is lower than one frame per delay seconds, then the camera's available frame rate will be used instead. Specify 0 for delay to take pictures as quickly as possible.

-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 and webcam 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 and webcam 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 Auto-Adjustment, below)

-R red
    Set the software red level, overriding automatic color balancing. Valid values: 64-255 (50%-199%).

-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.

-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: 8-320. Valid values in 32bpp mode: 16-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, and -y flags. The -s flag is no longer a factor, except in determining the maximum image size. Note: -x 320 -y 240 -s 2 is not the same as -x 320 -y 240 -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: 1) Run cqcam (not xcqcam) once with -a+ -r (adjustments on, "remember" the brightness) 2) 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. 3) 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. http://www.quickcam.com/connect/developer.html - The Connectix QuickCam developers' program.

COPYRIGHT
cqcam and xcqcam are Copyright (C) 1996-1998 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
We cannot properly drop root permissions under LynxOS, because port access in LynxOS requires that we be root the whole time (not just to enable access). Please see TODO for non-bug things that I want to change. To submit a bug report, please rebuild cqcam, specifying '--enable-debug' when you run configure. Then send the stderr output, along with what you consider to be relevent details, to:
  Patrick Reynolds <reynolds@cs.duke.edu>

AUTHORS

Primary author
    Patrick Reynolds <reynolds@cs.duke.edu>

Contributors
    Anders Arpteg <aa11ac@hik.se> Philip Blundell <philip.blundell@pobox.com> Ciaran Carter <ciaran.carter@stbrn.ac.uk> David Raufeisen <fortyoz@themes.org> Fabio Fregi and Giuseppe Guerrini <cni@bo.nettuno.it>,<dev6385@iperbole.bologna.it> Charles Henrich <henrich@crh.cl.msu.edu> Joe Ilacqua <spike@indra.com> Hakan Lennestal <Hakan.Lennestal@cdt.luth.se> Matt Mosely <mattm@igloo.org> Andre Jesmanowicz <andre@andrix.biophysics.mcw.edu> Shawn Stepper <stepper@vip.stanford.edu> Simon Thornington <simon@hasc.com> Joe Zbiciak <j-zbiciak1@ti.com>