This is GNU public license software. See COPYING for details.

Author: Philippe Serbruyns <ps@telin.rug.ac.be>

Many thanks to Pascal De Petter <research@velleman.be> for pointing me out how
to configure this videograbber!

1) What is this?
----------------
The k8100grab is a videograb utility to record video frames with the Velleman 
K8100 kit.

This version of k8100grab lets you view or save frames coming from the
Velleman K8100 videograbber. See http://www.velleman.be/kits/k8100.htm about
the hardware.
Viewing is done by the svgalib(7) library functions, thus you should run this
tool from a console, not from the X Window system!
Full rate depends on your hardware you're using. It is possible to capture 
quarter frames to increase speed, or you can specify delay's between grabs
to monitor slowly evolving actions.

2) Install
----------
You should have svgalib installed. The latest version of svgalib can be found
on sunsite.unc.edu in /pub/Linux/libs/graphics or tsx-11.mit.edu in 
/pub/linux/sources/libs as svgalib-X.X.X.tar.gz. 
You may have to edit the k8100grab.c file to set up the IO address on the K8100
Velleman card if you're not using the default 0x300 at line 25. 
Type:
% make
And as super-user:
# make install
Svgalib requires direct I/O from the videocard, so k8100grab is set with the
setuid bit to "root".
k8100grab and 2 script tools conv2any and blankuv are copied to /usr/local/bin
(see next section on what these do).
A manual page is also copied to the /usr/local/man/man1 section, so you can run:
% man k8100grab

3) Tools
--------
You should have ImageMagick installed. The latest version of ImageMagick can be
found with ftp on gd.tuwien.ac.at in /pub/graphics/ImageMagick/linux.
This tools lets you convert the generated files to many popular image formats or
even MPEG video.

To convert raw video frames you must specify the picture size, either 512x512
or 256x256 when you use small frames. To capture and convert to a JPEG 
with contrast enhancement use:
eg. k8100grab -w test.gray
    convert -contrast -size 512x512 test.gray test.jpeg
To capture and display a small raw frame:
eg. k8100grab -s -w test.gray
  (after starting the X Window System)
    display -size 256x256 test.gray

However, I added support for the PGM (Portable Grayscale Map) graphics file
format, that means a header is include so you don't have to specify the
resolution anymore :-).
eg. k8100grab -p -w test.pgm
    convert test.pgm test.jpeg				# convert to JPEG
Use this to convert a bunch of video frames to any format:
eg. k8100grab -f 1000 -p -w test%04d.pgm		# capture 1000 frames
    mogrify -contrast -format png *.pgm			# convert to PNG
A shelltool "conv2any" is provided as an example to convert *.pgm files to any
format, one by one, with deletion of the original (if you lack diskspace).
eg. conv2any -contrast -format tga *.pgm		# convert to TGA

For MPEG video you should have mpeg2vidcodec installed. The latest version of
mpeg2vidcodec can be found with ftp on ftp.mpeg.org in /pub/mpeg/mssg.
This tool lets you convert the raw gray files to an MPEG video stream.
Two sample MPEG-parameter files are include: MPEG-1-256x256.par and
MPEG-1-512x512.par as an example for small or normal captures. These text files
can be changed a bit to addapt your needs. e.g. name of frames to convert,
total number of frames, number of first frame,  horizontal_size, vertical_size,
bit_rate (bits/s), etc... There is a shortcut in creating the chroma files:
they can be zeroed (well 128 exactly), because we use gray captures.
Two blank chroma files blank256x256.UV and blank512x512.UV are included, which
can be used as links for the gray frames. A tool "blankuv" is included to
generate blank *.U and *.V chroma files for each gray frame (*.Y) with soft
links.

Here is an example how to capture an MPEG "film.mpg" in the small format.
k8100grab -s -f 100 -w test%04d.Y		# generate test frames *.Y
blankuv -s test*.Y				# generate chroma frames *.U,*.V
mpeg2encode MPEG-1-256x256.par film.mpg		# generate the MPEG stream

You can use mpeg_play or MpegTV Player to view your MPEG video's. The first
one is available with ftp on mm-ftp.cs.berkeley.edu in /pub/mpeg, and the
second on URL http://www.mpegtv.com/download.html.

4) TODO
-------
Color! The Velleman k4600 Video to RGB convertor can be used to get color.
Obviously we'll need a color camera too. Anybody giving me one?


Please e-mail me if you have a problem about this program or you got your
card working with linux. I'm intrested in how many people use Linux and the 
Velleman K8100 kit.

There is a home page provided for the k8100grab in 
http://telin.rug.ac.be/~ps/k8100grab

Enjoy!
Philippe Serbruyns <ps@telin.rug.ac.be>
