CHANGES in qcam 0.91

I've added edge detection, accessible with the "-e" flag.

I've added window inflation with the "-S" flag.  The picture with "-s 4"
is just too small to see.  The "-i" flag interpolates intermediate
pixels to help depixelize the image (this is *slow*!).

I've added "const" qualifiers to the qcam parameter where appropriate,
hoping to help the optimizer.  It seems to make a slight difference.

I've renamed this file to CHANGES so that the README file isn't a
horrible reverse history of qcam.

README for qcam 0.9

In order to get inlining to work, I've made "qcam-os.c" get #included
into qcam-lib.c.  This speeds things up about 10% on my machine, so I
forgive myself for the ugly #inclusion of a C file.

Now that locking is working properly, I've eliminated the qc_reset at
the end of each scan.  This also speeds up scans.

I've restored a usleep(250) to the qc_reset, as required by the
Connectix docs.  This doesn't harm speed much, since qc_reset isn't
called as often now.

I've added a "-d file" parameter to qcam only, which dumps the "struct
qcam" structure to "file" in a format suitable for reading in as a
qcam.conf.

Brian Scearce (bls@pathetique.com)
November 17, 1996.

README for qcam 0.8

Ed Orcutt's autoexposure code has been moved into a separate library.

To use Ed's modifications, use the "-E" parameter.  It takes up to
five parameters.  They are, in order:

  mode target-lum tolerance-lum std-target-lum std-tolerance-lum

"mode" is an integer.  Modes 0 and 1 examine the average brightness of
the picture, and adjust the brightness until the average pixel luminance
is in range.  Mode 0 looks at the whole picture; mode 1 looks at only
the center ninth of the picture.

Mode 2 adjusts contrast to get the standard deviation of the pixel
luminance into range.

Ranges are specified in the next four parameters; if they are not
supplied, reasonable defaults are used.

The -H parameter adds a histogram of pixel values to the image.

I've added code to remove the dark current speckling.  To use it, you
first have to run the "make.darkmask" program.  Put the Cam in a dark
place and run the program.  It will record the dark current leakage for
each pixel.  Then, you can run qcam or xqcam with the "-D" option, which
will remove dark current speckling.

I wrote a man page.  Suggestions for improvement welcome.

README for qcam 0.7

I've integrated some autoexposure code from Ed Orcutt (edo@eosys.com).
This is part of the qcam application, not the qcam-lib interface, so
autoexposure only works on qcam, not xqcam.

xqcam still "smears" pictures when width % (20*transfer_scale) != 0, so
I've added some parameter checks to xqcam.  Rather than fix the bug, I'm
just more stridently announcing it.

There's a new entry point, qc_forceunidir(q), which forces the parallel
port to operate in unidirectional mode.  qcam and xqcam access it via
the -u flag.  It's theoretically possible to force bidir as well, but I
haven't added an entry point to set that flag.

README for qcam 0.6

Dave Plonka (plonka@carroll1.cc.edu) wrote the locking code that Scott
Laird asked for in qcam-Linux.c, so there is now functioning locking in
the qcam library!

I've finally upgraded my machine so that it can use X, so I debugged
xqcam to work with the updated libraries.  The only logical spot I could
find to put auto white balancing slows the program down tremendously, so
I recommend you don't use it.  xqcam can't handle the -f (pick a
qcam.conf file) argument.

xqcam displays a "smeared" picture (horizontal sync off) for cases where
width/transfer-scale is not divisible by 20.

xqcam now uses the -x/-y/-t/-l/-s flags as documented under the 0.3
notes.  Dave Plonka has also added a "-r" flag that releases the lock
with every scan, to allow multiple locking programs to access the cam in
turn.

I still don't know how to compile xfqcam, so it probably still doesn't
work.

Brian Scearce (bls@pathetique.com)
August 24, 1996


README for qcam 0.4a

Hanno Mueller (hmueller@kabel.de) sent a fix for the autocalibration
code.

I've changed the qcam.conf reader so that it can set top, left and
transfer (scale), and reports values out of range (except for port) and
does not use the bad values.  Also, lines have to be better-formed;
Scott's worry that "report" on a line will set the port to zero won't
happen.

There's also a -f option now to specify a file other than CONFIG_FILE
for reading options from, useful for people with more than one cam on
more than one parallel port.

Brian Scearce (bls@pathetique.com)

README for qcam 0.4

I've added bidirection port support, which makes data transfers about
three times faster on parallel ports that support it.  The flags have
changed significantly to be in closer accord to the software interface
of the QuickCam.  The QuickCam CCD is 336x243.  The leftmost 12 pixels
are always black.  The -x and -y flags are now in terms of the CCD area,
so specifying "-x 160 -y 120" now gives you 1/4 of the CCD area, not a
shrunken image.

For shrunken images, use the new "-s" transfer-scale flag.  "-s 1" is
full sized (default), "-s 2" is half (in each dimension, so 1/4 of the
pixels are actually transmitted), and "-s 4" is quartered.

-x and -y now specify the lengths of the sides of a rectangle to be
viewed; to change the origin of the rectangle, use -t and -l to set the
top and left lines.  Ranges are 1-243 (default 1) and 1-336 (default 14,
must be even), respectively.

Example: to get a 100x100 picture centered on the usable area of the CCD
(i.e. ignoring the 12 black pixels on the left), you'd use:

	-x 100 -y 100 -t 71 -l 124

( (243-100) / 2 = 71, (324-100)/2 + 12 = 124).

There's also a -W flag to do autocalibration of white balance.

Compile with -DDEBUG if you want lots of chatter.

Brian Scearce (bls@best.com)

README for qcam 0.3

This is the fourth alpha-test release of my control program for the
Connectix QuickCam parallel port video camera.  It enables you to take
pictures with the camera at 320x240, 160x120, or 80x60 using 4 or 6
bits per pixel.  This program may not work with your camera, and could
possibly damage your system if used improperly.  Use at your own risk.
This version is intended primarily for testing, and has many small
changes.  It may not work on your hardware.


New Features since 0.2:
-----------------------

I've made autoprobing for the QuickCam the default if a port isn't
specified by the user.  This should be safe, but it may not always
find the camera.  Once you locate the camera, you should edit the
qcam.conf file and set it to the correct port.

This release include two versions of the xqcam program.  The first is
the original (from Paul Chinn) that's only slightly different than the
previous version.  I've tried to add some additional debugging, but
it's mostly the same.

The second is his new version with on-screen controls for pretty much
everything.  Unfortunately, it requires the Xforms library, which I
don't have.  I wanted to release what I have, so I disabled it in the
Makefile.  If you want to use it with this release, you'll probably
have to make a few changes to get it to work.  Hopefully someone will
fix it and contribute the patches back to me for version 0.4.

There aren't many other visible changes in this release, but I've made
a lot of small changes to the library.

I've temporarily disabled locking because it doesn't actually work
right more than half the time.  Any volunteers?

I've started on bi-directional support.  It doesn't actually work yet,
but there's a stub for it, and it should be automatically detected.  I
suspect this can be finished in about 5 lines of code, but I don't
have the hardware to test it.

I've added Paul Chinn's changes to make 4-bit mode work correctly.

I've combined qc_scan and qc_scanconvert.  This gives a whopping 1%
speed boost on my machine (Pentium 90), plus it's a bit cleaner.  This
changes makes qc_scan return the same output that qc_scancovert used
to return.

I've added a bunch of get/set functions for manipulating the qcam
structure from client programs.  They aren't needed yet, but they give
a cleaner interface and should make it easier to update the library
without breaking programs.

I've cleaned up the comments in most of the code.


Hopefully the few small changes to xqcam will help.  I haven't had
time to make any major changes, but I have fixed a few small things,
and I've tried to check the return values for most of the X calls that
seem likely to fail.


Future Changes:
---------------

Documentation needs to be written, for the programs, the library, and
the protocol.

I'm planning on adding support for "zoom mode," where the resolutions
on the scan command and the resolution command don't match.

I'd like to get support for bi-directional ports working.

Some people are working on ports to DOS, Windows, OS/2, and possibly
an embedded system.  I don't want to kill any of them, if it can be
avoided.

I think I'm almost done making large changes to the library, so 



Usage:
------

  qcam [options] [filename]
    Options:
      -x width   Set width
      -y height  Set height
      -p port    Set port
      -B bpp     Set bits per pixel
      -c val     Set contrast
      -w val     Set white balance
      -b val     Set brightness
      -V         Print version

The program returns one image from the camera on standard output in
PGM format.  The default resolution is 160x120, and the default port
is 0x378 (LPT1).  There are command-line arguments to change these as
well as a configuration file.  If your camera is on your first
parallel port (0x378 or /dev/lp1), then your should be able to run the
program with no options and get a picture.  If you are unsure which
port your QuickCam is on, run probeqcam as root, and it should tell
you.

There's also a xqcam program that takes the same options, plus two
more:

      -v         Verbose:  print frames-per-second.
      -C         Use private colormap.


Since these programs need access to the parallel port control
registers, they must be run with root privileges.  By default they are
installed SUID root.  They should be safe and should not pose a
security threat, but you should be careful.


Credits:
--------

Several people have contributed to this, including Paul Chinn, Thomas
Davis, Simon Janes, and Russell Nelson.


Copyright:
----------

I've placed this program under the same copyright the X Consortium
uses.  Basically, it's free for any use whatsoever.  If this manages
to cause great problems for anyone (?) let me know and I suspect we
can arrange something.

Here's the notice:


Copyright (C) 1996 by Scott Laird

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL SCOTT LAIRD BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.


Bugs:
-----

This program has bugs.  The known ones should be listed in the BUGS
file that comes with this program.  Please send bug reports/fixes to
me at scott@laird.com, and I'll try to get the bug fixed for the next
version.


FTP Site:
---------

The latest version of this program can be found in
ftp://ftp.nas.com/laird


Mailing List:
-------------

There is a mailing list for discussing the QuickCam and Linux at
linux-connectix@crynwr.com.  Send mail to
linux-connect-request@crynwr.com to be added to the list.



Scott Laird
scott@laird.com
January 6, 1996.