qcread- Image reader and routines for Connectix QuickCam control.
Version 0.3, beta release by Alex Belits, email@example.com. partially based on
qcamby Scott Laird, firstname.lastname@example.org.
cqc.c, cqc.h): Berkeley-style, freeware.
qcam(by Scott Laird, email@example.com), although it uses ideas from it and is designed to peacefully coexist with it. Design is based on Connectix QuickCam specifications and discussions in quickcam-drivers mailing list, other resources at http://www.crynwr.com/qcpc/.
This program supports both color and B&W parallel-port Connectix QuickCam for PC. All modes are supported except color QuickCam "thousands colors" compressed download and 640x480 "billions colors" mode. "Thousands" is unsupported because of the lack of information and will be added if Connectix will give the documentation on it to developers in the same or similar way, the documentation on other modes was given that made this program possible. "Billions colors" will be supported in later releases.
This program does NOT do any "guesswork" manipulations on unknown hardware (such as probing ports) or self adjusts any parameters. The only thing, it determines by itself completely is the type of camera (color or B&W). It can determine, if the parallel port is uni- or bidirectional, although user can override that in configuration file or from command line. To prevent "hanging" if hardware behaves unexpectedly, it uses alarm -- any operation that takes longer than the alarm time (defined as QCAM_ALARM_TIME == 10 seconds) finishes with an error, so "heartbeat" isn't used. With exception for this feature and bidirectional/unidirectional ports detection, program behaves the way, it's described in the hardware documentation. Also no attempt has been made to process or filter the output, although in future releases "christmas lights" removing, barrel distortion and uneven brightness level compensation will be added (either original, or some existing package for that purpose will be used). While it's a good idea to fix flaws in the image before it will be processed by other programs, the main goal currently is to handle hardware correctly and efficiently (at least as efficient as it's possible for this device).
Currently Linux and FreeBSD are supported, although ports to other PC-based unices will be added. No ports to non-unixlike systems are planned.
Reliability of the program was tested at the constantly-running webcam page at http://phobos.illtel.denver.co.us/qcam-frame?update=serverpush and other webcam sites. While different kinds of hardware were used for testing, no problems yet were found.
Configuration and lock files use the same format/names as ones for
qcam, although handling routines are different. Some keywords are
qcam ones, although
qcam can share the same file because all common keywords are
handled the same way. Command line switches are similar and mostly compatible
os-specific.hfile, FreeBSD-specific routines added. Makefile modified.
libc. Porting to systems with different
libcrequired adding GNU
getoptinto distribution. License for image reader changed to GPL.
qcreadsends its output to the standard output in raw PPM or PGM format.
qcreadcreates and locks the file "
/tmp/LOCK.qcam.0x<port>" when it opens the camera at the port <port> (in hex). File remains when the camera is closed or program exits. This behaviour is compatible with
qcam, although file permissions are set to
0600for security reasons -- to prevent locking by non-root user. If the file is locked, open waits until it's unlocked.
qcreadcommand line options
#' (hash sign) and a newline are ignored and assumed to be comments. Default config file is "
Configuration file keywords for
qcread and "long" command line options for
qcread are the same and can be used interchangeably. Later mentioned option
overrides previous ones, and command line options override configuration file
ones. The only two command line options that determine how configuration file
will be processed are
--camera that determine
file and camera name. "camera" keyword with camera name parameter in the file
starts the section that will be processed only if camera of the same name
will be defined in the command line. Subsequent "camera" statements override
each other, but there is no way to finish camera section without starting new
one, so all common options should be before the first "camera" statement.
Multiple "camera" options in the command line behave like any other options,
only the last one is used, cameras can't be combined.
--port) option is the same as in
qcam, although value 0 is invalid,
qcread has no autodetection.
--porttype option determines the type of parallel port used, valid values are
bidirectional" and "
unknown" value or lack of this option causes autodetection to be used.
Camera direction (
--direction option) can be "up", "down", "left" or "right".
It represents, how camera is located from the viewpoint of its object:
"Normal" camera position is "up". "Width" (
--width) and "height" (
--height) are always counted in an
object's coordinate system -- if "landscape" image with camera direction "up"
will be width=320, height=240, "portrait" one with the same camera in "left"
direction will be width=240, height=320. Image width and height are the ones
before scaling down. Width for "up" and "down" and height for "left" and
"right" directions should be even, and odd values will be reduced by 1.
Image offsets from left (
--xoffset) ant top (
offsets from image edge, not CCD ones, so "black" rows/columns shouldn't be
counted. Color and B&W cameras use different physical offsets, and they are
added automatically. Camera direction is also considered, offsets are from
physically left-top corner of the image in the defined position. This differs
qcam, so option names are different. Left offset for "up" and "down" and
top offset for "left" and "right" directions should be even, and odd values
will be reduced by 1.
Priority for scanning can be changed using
using values for
setpriority(2). By default
process changes priority to the highest available value -20 when scanning.
Transfer scale (
--transfer) can be 1 (no
scaling), 2 (every second row and pixel) or 4 (every fourth row and pixel).
Image will be 1/2 or 1/4 of its original size in both directions.
--bpp option defines bit depth. For B&W camera valid values are 4
(16 shades of grey) and 6 (64 shades of grey). Color camera only supports 24
bits per pixel (8 bits per color component).
--brightness) and contrast (
define brightness and contrast of the image.
--blackoffset option define black offset
value for B&W camera.
qcam calls it "white balance" for some reason, so
in configuration file "whitebal" keyword is also accepted for compatibility.
--white options define black and white levels
for color camera. They use different set of values in the same conditions
(even though they are in the same range, B&W camera uses), so different
keywords were used.
--hue option defines hue (blue gain) for color camera.
define red, green and blue correction values for color camera.
Three correction values are weighted against each other and can't affect
--red 10 --green 20 --blue 15 means the same as
--red 1 --green 2 --blue 1.5.
--saturation options defines saturation for color camera. High
saturation value may cause "blooming" of light sources.
--verbose option makes
additional messages to
stderr, without this option only error
messages are printed at
stderr. There is no such keyword in the config file.
--version option prints
version and exits, there is no such keyword in the config file.
--help option prints the hessage:
Connectix QuickCam image reader, available options: -V, --version, print version number -f, --config FILE config file name FILE (default /usr/local/etc/qcam.conf) --camera NAME camera name NAME -p, --port N port number N (0xNNN - hex, NNN - decimal) --porttype TYPE port type TYPE (unknown, unidirectional or bidirectional) -b, --brightness N brightness N (0-255) -c, --contrast N contrast N (0-255) --white N white level N (0-255) -w, --blackoffset N black offset N (0-255) --saturation N saturation N (0-255) --hue N hue N (0-255) --red N red correction (0.004-1-255) --green N green correction (0.004-1-255) --blue N blue correction (0.004-1-255) --black N black level N (0-255) -l, --xoffset N left image edge offset (0-326) -t, --yoffset N top image edge offset (0-326) -x, --width N image width (2-328) -y, --height N image height (2-328) -B, --bpp N bits per pixel (4, 6 or 24) -s, --transfer N transfer scale (1, 2 or 4) --direction DIRECTION camera direction (up, down, right or left) --priority N scanning priority ("niceness" value) -v, --verbose verbose mode -h, --help this messageand exits, there is no such keyword in the config file.
Makefileif necessary (leave settings for your OS uncommented). Then run
make. Create directory
/usr/local/etcif necessary, place
qcam.conffile in it and set all necessary configuration parameters there.
qcread by piping its output through xv:
./qcread -v | (sleep 1; xv -)If
qcreadreturns errors, check parameters in the
Note: PCs that have parallel ports configurable through BIOS setup are often set into unidirectional mode while port supports bidirectional transfers. This configuration can't be detected reliably by
qcread, and could cause errors even if
qcreadis set into unidirectional transfer mode. Make sure that port is set into bidirectional port mode if it is supported.
qcreadis supposed to be used by root only. It reads file specified in the command line and displays lines, not matching the format of its config file, increases the priority of itself and is extremely resource-consuming, so making it setuid root will be dangerous. Even with config file diagnostics removed high load it creates on the system is enough to disallow its use for "normal" users. It's also recommended to create lock file before use to prevnt users from creating and locking their files. Lock file is located in
/tmp, so otherwise different kinds of abuse are possible if program can be started automatically. However
qcreadnever reads or writes lock file.