Camera Interface

(Unix version only) Acquires an image from a camera, with a user-supplied driver. For example, images can be acquired from the Connectix QuickCam 2 using the program cqcam, available from: www.cs.virginia.edu/~patrick/quickcam

A driver is a command-line program that writes a file to standard output in PNM format. Tnimage controls the driver using the driver's command line parameters, which are stored in a configuration file when the camera is given the ``initialize'' command.

Below is the procedure for configuring a new camera interface, if it has not already been set up automatically by the Install program:

1. Add the name of a configuration file you will create named, for example, ``mycamera'' to $HOME/.tnimage/cameras on a new line. Note that the same driver can appear a number of times, each referring to a different configuration file with different default parameters.

   For example:

    
           quickcam
           mycamera
           my_other_camera
           mycamera-at-320x200
   

2. Create the ``mycamera'' configuration file in the directory $HOME/.tnimage containing the following lines, which describe the command-line options required by the driver (without numerical values). Below is a typical example, with quickcam options added:

   driver /home/you/camera/cqcam	Path for driver binary
   defaults /home/you/.cqcrc	Path for driver's configuration file (see below)
   other -32+	Any other command line options.
   scale -s	Driver's command to set scale
   width -x	Driver's command to set width.
   height -y	Driver's command to set height.
   brightness -b	Driver's command to set brightness.
   black -B	Driver's command to set black level
   white -w	Driver's command to set white balance
   hue -H	Driver's command to set hue (blue level).
   saturation -S	Driver's command to set saturation
   contrast -c	Driver's command to set contrast.
   initialize -a+ -r	Driver's command(s) to initialize the camera.
   normal -a-	Command(s) to acquire an image normally.
   extra	Any other command line options.

   Anything entered after ``other'' will be placed immediately after the driver name on the command line. In this example, -32+ was added as a sample ``other'' command line option (this causes the driver to produce 32-bit/pixel output).

   The ``initialize'' command should also include any options for automatically saving the driver's new configuration in its config file ( -r in this case).

   Anything entered after ``extra'' will be placed at the end of the command line. In this example, no extra commands will be sent.

   Change the command-line options as needed for your driver. The numerical values for the above parameters will be supplied by tnimage.

   Any of the above options may be omitted if desired.

   NOTE: Each camera driver has different command-line options. For example, the ``-s'' command sets the scale for cqcam but other camera drivers may use a completely different command line option. Consult the driver documentation before creating a config file.

   Next, add the following default parameters to the ``mycamera'' configuration file, along with the desired numbers. Change the width and height to match the image size produced by the camera:

   #default parameters	A comment (begins with #)
   default_shell 1	1= put camera image in a separate, positionable window.
   default_width 640	Width in pixels of image created by camera.
   default_height 480	Height in pixels of image created by camera.
   default_scale 1	Starting scale value for camera.
   default_depth 3	Bytes/pixel of image produced by camera.
   default_post_command	Post-processing command

   If ``default_shell'' is 0, the camera image will appear on the main tnimage window; otherwise, it will be placed in its own separate, positionable frame.

   The default_post_command can be any tnimage command or macro. If the box beside the command is checked, this command will be executed as a macro after every frame. For example, the line

           default_post_command filter(1,1,10);
   

   Will sharpen the image by 10% using a 3x3 sharpening filter after each frame. See Sec. 13 for details on macros.

   A common use of post-processing is to adjust the image color. This can be done by entering a mathematical formula (See ``image algebra'', Sec. 12), for example,

   r+=20;

   to increase the brightness of the red component by 20 (on a scale of -255 to 255). For simple commands such as color or brightness adjustment, it is usually much faster to use the corresponding macro command, i.e.:

   color(0, 20, 0, 0);

   which will do the same thing, nearly instantaneously.

   Note that the post-processing command is not executed unless the box next to it is checked.

3. (Optional) If the camera driver does not create its own defaults file, create another text file (named, for example, `.cqcrc') describing the starting default values, containing the following lines:

   contrast 104	Contrast
   white 100	White balance
   blacklevel 100	Black level
   hue 110	Hue (blue level)

   Put the name and path of this .cqcrc file after ``defaults'' in the first (`mycamera') file. These parameters will be the starting default values for the camera. (Note: cqcam produces a .cqcrc file automatically). During initialization, the dialog will automatically be updated to reflect the new settings in the defaults file.

As an example, here is the $HOME/.tnimage/cameras file on my system:

      quickcam

Here is the $HOME/.tnimage/quickcam file on my system:

     # tnimage configuration file for connectix quickcam
     # order of parameters may be important

     # command-line options for camera driver
     driver /home/tjnelson/camera/cqcam-0.45a/cqcam
     defaults /home/tjnelson/.cqcrc
     other -32+
     scale -s
     width -x
     height -y
     brightness -b
     black -B
     white -w
     hue -H
     saturation -S
     contrast -c
     initialize -a+ -r
     normal -a-

     # default parameters
     # 0=put camera image on main window, 1=put in separate window
     default_shell 1

     # width and height of image produced by camera
     default_width 640
     default_height 480

     # scale of image as defined by camera driver
     default_scale 1

     # depth of camera image, in bytes/pixel
     default_depth 3

     # default post-processing command or macro name
     default_post_command filter 1 1 10

Here is the $HOME/.cqcrc file on my system, which was created by the driver:

     brightness      127

A camera config file and a patch for the bttv driver for the Hauppauge WinTV camera card is included in the file bttv_kit.tgz. (This file was contributed by Michael Lapsley (mlapsley@sthelier.sghms.ac.uk)).

Camera Dialog Options

Acquisition mode

1. Normal: Each frame replaces the previous frame.
2. Accumulate frames: Successive camera frames are averaged with all previous frames. This can greatly improve the quality of the image.
3. Add: The new frame is added to the previous frame. This can be used to increase the sensitivity of images collected in low light conditions.
4. Subtract: The new frame is subtracted from the previous frame. Camera images often contain streaks or abnormally bright pixels caused by camera imperfections. The `subtract' option can be used to subtract these from the image. After acquiring an image, cover the lens (or turn off the light), click on ``Acquisition mode.. Subtract'', ``Camera..normal'' and ``Frames..Single frame''. Then click on ``Acquire frame'' to collect one frame of dark background pixels. The deviation of each rgb value in the dark image from the average rgb values for each scan line will subtracted from the previous image.

in For example, below is a low-resolution image of an infrared TV remote control created using a QuickCam (which is sensitive to infrared as well as visible light). The original top image A contains numerous vertical streaks. Subtracting the dark current produced B. The vertical streaks are mostly eliminated, although the picture is more grainy. This could have been repaired by accumulating several frames. Darker scenes are more susceptible to dark current artifacts.

Camera

1. Initialize: Sends the ``initialization'' command to the camera. This can take 10 times as long as acquiring an image. The camera is also initialized automatically before the first frame. The camera dialog will be automatically updated to reflect the contents of the ``defaults'' file.
2. Acquire: Obtain frames normally. The menus may become relatively unresponsive while a frame is being acquired.

Frames

1. Continuous: Tnimage continually acquires new images at the specified frame rate. The desired frame rate may not actually be achieved due to limitations in the camera camera driver. The ``camera'' setting should always be set to ``normal'' during continuous operation, otherwise the camera will be initialized on each frame which will greatly decrease the frame rate.
2. Single frame: The program waits until the ``Acquire frame'' button is clicked, then takes a single frame.

When the ``OK'' button or the main ``Cancel'' buttons are clicked, image acquisition stops and the dialog box disappears, leaving the camera image that is currently visible as the final image.

Notes:

1. If the camera driver requires root permissions, tnimage must either be set suid or run as root.
2. The image data are sent through a fifo and do not use a temporary file.
3. To stop acquiring frames continuously without dismissing the camera dialog, click on the "Frames..Single frame'' button.
4. When acquiring frames continuously, if the dialog buttons become unresponsive, click on the ``Cancel'' button on the main tnimage window. This will usually stop image acquisition.
5. Do not exit tnimage while acquiring an image. This will create a zombie process.
6. With some camera drivers, the driver's config file is not automatically updated by the camera driver. The symptom of this is that, when several frames are collected, the first frame is normal (because initialization of the camera is occurring), but subsequent frames are completely black or gray. The solution is to set the brightness value manually in tnimage.