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:
        o Connectix B?W QuickCam for PC.
        o Connectix Color QuickCam for PC.
        o on unidirectional or bidirectional parallel ports.
Output formats:
        o For color images - raw PPM.
        o For B?W images - raw PGM.
Operating systems supported:
        o Linux.
        o FreeBSD.
Used in:
        o qcwebcam - QuickCam-based webcam program for fhttpd.
Copyright and license:
        o Library (cqc.c, cqc.h): Berkeley-style, freeware.
        o Reader utility, support files: GPL, freeware.
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:

        O
  __   _L     __        __
 (==) (==)   ([])-O  O-([])
  ~F   ~~     ~~        ~~
   O
  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/
