/* 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)
d9e41c4de0