qcread - Image reader and routines for Connectix QuickCam control.
Version 0.2, beta release
by Alex Belits, abelits@phobos.illtel.denver.co.us.
partially based on qcam by Scott Laird, scott@laird.com.
cqc.c, cqc.h): Berkeley-style, freeware.
qcam.
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/pub/qcam/qcam.html 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.
os-specific.h file, FreeBSD-specific
routines added. Makefile modified.getopt added.
getopt from Linux
libc. Porting to systems with different libc
required adding GNU getopt into distribution. License for
image reader changed to GPL.
qcread sends its output to the standard output in raw PPM or PGM format.
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#' (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.
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.
--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)
-c, --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)
--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)
--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)
-v, --verbose verbose mode
-h, --help this message
and exits, there is no such keyword in the config file.
qcreadMakefile 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 byqcread, and could cause errors even ifqcreadis set into unidirectional transfer mode. Make sure that port is set into bidirectional port mode if it is supported.
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.