/* README for libgphoto2/camlibs/sonix camera library
 *
 * Copyright (C) 2005 Theodore Kilgore <kilgota@auburn.edu>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

This library originally supported the stillcam functions of the Vivivar 
Vivicam 3350B, which uses the sn9c2028 chip from Sonix (Vendor ID 0x0c45). 
The recently discovered Sakar Digital Keychain #11199, uses the same controller
chip but there are some other, radical differences between the two cameras. 
The library, which was originally written to support the Vivicam 3350b, 
has now (August 2006) received major revision, so as to support both cameras. 

The functionality of the two cameras can be distinguished by a four-digit 
hexadecimal number, which apparently is a firmware version and/or an identifier
for the video sensor chip. If you have a Sonix sn9c2028 camera which returns 
a number not listed in sonix.c, then your camera may or may not work with this 
code. Please inform if you get a different ID number!

Here we give a brief description of both currently-supported cameras and the 
supported gphoto2 functions for each.

Vivicam 3350b:

The 3350B uses an OV7630 sensor and produces a maximum resolution of 640x480 
and an option to use 320x240. The photos are all compressed. The compression 
scheme is lossy and seems to be a variation on RLE. The decompression 
algorithm originates, I understand, in the work of Bertrik Sikkens for the 
sn9c102 cameras. In the macam project for MacOS-X camera support(webcam-osx 
project on Sourceforge), the decompression algorithm for the sn9c2028 cameras 
was developed by Mattias Krauss and adapted for use with the Vivitar Vivicam 
3350B in particular by Harald Ruda <hrx at users.sourceforge.net>. Harald 
brought to myattention the work already done in the macam project, pointed out 
that it is GPL code, and invited me to look at what they had done. Thanks, 
Harald. 

Features of the camera include the ability to delete all photos. The "delete 
last" function may work, but the "capture-image" function does not seem to 
work when tested with my Vivicam 3350B (delete last and capture definitely
do work with the Sakar Digital Keychain camera therefore are implemented). 
Yet another camera which the macam driver also supports has been listed here 
as a supported camera. It apparently uses 352x288 and 176x144 resolution 
settings. I know of it only second hand, have not personally tested it, and 
would appreciate any reports about it (I suspect it is similar to the Sakar
Digital Keychain camera), as well as any other cameras which seem to 
have the same chip. These cameras also can act as pccam or webcam. They use 
isochronous transfer to do that. Support for this feature in Linux requires 
a kernel module. That is a possible future project, but the requirement for 
direct kernel support precludes using the webcam functionality to 
facilitate any of the capture options of gphoto2. 

The following description of the Vivicam 3350b compression is derived from  
remarks found in the macam source code. 

    The video in the data stream is a GRBG-Bayer pattern (compressed by some 
    sort of run-length encoding and Huffman compression). The data stream 
    format is as follows:

    <frame 1 header>
    <line 0, bytes 0 and 1, "true" values>
    <pixel 1 bitcode>
    <pixel 2 bitcode>
    ...
    <pixel (width - 1)  bitcode>
    <line 1 first two bytes, "true" values>
    ...
    <line (height - 1) first two bytes, "true" values>
    <padding bits>
    <frame 2 header>
    ...

    The frame header is 12 bytes long 
    (0xff 0xff 0x00 0xc4 0xc4 0x96 
    0x00 0x<*1> 0x<*2> 0x<*3> 0x<*4> 0x<*5>). <*1> seems to be a frame counter 
    (bits 6 and 7) and a size indicator 
    (bits 1 and 2: 00=VGA, 01=SIF, 10=QSIF) Bit 0 seems to be always 1, 
    4 and 5 seem to be always 0. Bit 3 is often 0 (but not always).
    <*2> to <*5>'s meanings are probably some sort of brightness 
    summary/average (Note: this is the opinion of the macam developers, or 
    perhaps it is true in webcam mode. For still photos the header appears 
    to contain only the first 8 bytes described here).

    After that, the video lines follow. Each line starts with two 8-bit 
    starting values, representing "actual" data - since it's a Bayer pattern, 
    there are two color components alternating in each line. Both components 
    are tracked individually and independently (just alternating). Thus, the 
    decompression scheme must expand two bytes at a time, then move on. 

    After the first two starting values in a line, the encoded pixels follow. 
    For each pixel, there's a code in the stream that describes the next 
    component value. It can either be described as a change from the last 
    value of that component or as a direct value. These codes are not bound 
    to bytes - it's a pure bitstream. Codes have different lengths, according 
    to their likeliness. The algorithm is similar to Huffman compression, the 
    main differences are 
	a) the two modes, 
	b) the bit codes seem to be handmade, 
	c) there's some redundancy because of the two description modes 
	and 
	d) not all possible values exist - therefore, the values had to be 
	quantized (i.e. this compression algorithm is lossy). 

    The codes are as follows:

    0 			: 0 (leave as is)
    1000		: +8
    1001		: -8
    101 		: +3
    110 		: -3
    11100		: +20
    11101xxxxx 		: =8*(xxxxx)+0 (these values seem 
			to be unprecise - especially for low values)
    1111		: -20



The decompression algorithm used here is functionally identical to what is 
used in the macam driver, but is considerably streamlined. It seems to work 
perfectly, except that brightness and/or gamma need sometimes to be adjusted, 
especially for photos taken in dim light. 

Sakar Digital Keychain #11199:

This camera does _not_ use data compression in any of its stillcam functions.
It will hold 18 photos at 352x288 resolution, and 70 photos (or a a clip 
containing at most 70 frames) at 176x144 resolution, or any combination of 
these which does not fill up the camera. 

Clips are counted as individual entries. The number of frames in a clip 
is information which is unavailable until after the clip is downloaded, at 
which point the number of frames can be calculated based on the size of the 
downloaded data (!). As a result, it is impractical to save clips as 
consecutive still photos within the framework of gphoto. The OEM software
saves clips as AVI files, and that is done here, too. It seems to be just 
about the only way.

This camera also supports gphoto2 --capture-image, which will cause a photo
to be taken and stored among the photos on the camera for later download (the
capture dimensions are always 352x288). 

The photo just shot can of course be downloaded immediately using 
gphoto2 -p (its number, which will be the last taken) and, if desired, can
be deleted immediately afterwards using gphoto2 -d (its number) which this 
camera also permits (unlike the Vivicam 3350b).

GUI frontends:

Libgphoto2 , of course, permits the use of a GUI frontend as well as the 
gphoto2 command-line utility. I have tested my two cameras with gtkam and with 
flphoto. Both of them work, with the following provisos:

-- There is an unresolved problem with gtkam, when the Sakar Digital Keychain 
camera is hooked up and gtkam is started. The LED display starts to move 
immediately and keeps on. The LED activity does not stop when gtkam is exited,
but only on camera disconnect from the computer. This phenomenon may be quite
harmless, but who knows? It obviously means that some kind of background 
activity is taking place inside the camera. This LED activity does not occur 
if the gphoto2 command line or the gphoto2 shell or flphoto are used. 
(UPDATE: A workaround patch has been applied, which seems to fix this, as of
08/17/06)


-- flphoto will give a message when asked to save an AVI file, that it cannot
put the AVI file into an "album." Well, perhaps not. But not to worry. 
It will save the AVI file anyway, even while protesting. 


(This file revised 08/17/2006)