qcread - Image reader and routines for Connectix QuickCam control.

Version 0.3, beta release by Alex Belits, abelits@phobos.illtel.denver.co.us. partially based on qcam by Scott Laird, scott@laird.com.

Disclaimer

Author is not affiliated with Connectix Corporation, Connectix Corporation does not support or approve this software.
All copyright notices and disclaimers in sources and documentations are valid and assumed to be known by the user.

Hardware supported:
Output formats:
Operating systems supported:
Used in:
Copyright and license:
No any additional software required for initialization and capture.
Partial compatibility with qcam.

Description

qcread is NOT qcam (by Scott Laird, scott@laird.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 different from qcam ones, although qcread and qcam can share the same file because all common keywords are handled the same way. Command line switches are similar and mostly compatible to qcam.

Changes in version 0.3

Color correction options
red, green and blue options added.
Priority value option
priority option added.

Changes in version 0.2

FreeBSD support
OS-specific code moved to os-specific.h file, FreeBSD-specific routines added. Makefile modified.
GNU getopt added.
Original Linux-only version used GNU getopt from Linux libc. Porting to systems with different libc required adding GNU getopt into distribution. License for image reader changed to GPL.

Output

qcread sends its output to the standard output in raw PPM or PGM format.

Lock files

qcread creates 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 0600 for security reasons -- to prevent locking by non-root user. If the file is locked, open waits until it's unlocked.

qcam.conf format and qcread command line options

Configuration file contains a list of options and values, space separated with one keyword/option pair on a line. Blanks and blank lines are ignored, all characters betwen '#' (hash sign) and a newline are ignored and assumed to be comments. Default config file is "/usr/local/etc/qcam.conf".

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 -f (or --config) and --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.

-p (or --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 "unknown", "bidirectional" and "unidirectional". "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:
up down left right

"Normal" camera position is "up". "Width" (-x or --width) and "height" (-y or --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 (-l or --xoffset) ant top (-t or --yoffset) are 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 from 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 --priority option using values for nice(1)/setpriority(2). By default process changes priority to the highest available value -20 when scanning.

Transfer scale (-s or --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.

-B or --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 (-b or --brightness) and contrast (-c or --contrast) parameters define brightness and contrast of the image.

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

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

--red, --green and --blue options define red, green and blue correction values for color camera. Three correction values are weighted against each other and can't affect overall brightness: --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.

-v or --verbose option makes qcread print additional messages to stderr, without this option only error messages are printed at stderr. There is no such keyword in the config file.

-V or --version option prints qcread version and exits, there is no such keyword in the config file.

-h or --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 message
and exits, there is no such keyword in the config file.

Installing qcread

Unpack the tar archive, edit Makefile if necessary (leave settings for your OS uncommented). Then run make. Create directory /usr/local/etc if necessary, place qcam.conf file in it and set all necessary configuration parameters there.

Test qcread by piping its output through xv:

./qcread -v | (sleep 1; xv -)
If qcread returns errors, check parameters in the /usr/local/etc/qcam.conf file.
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 qcread is set into unidirectional transfer mode. Make sure that port is set into bidirectional port mode if it is supported.

Security

qcread is 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 qcread never reads or writes lock file.

Distribution site

FTP:
phobos.illtel.denver.co.us: /pub/qcread
HTTP:
http://phobos.illtel.denver.co.us/pub/qcread/