MARS MR97310 STILLCAM DRIVER
Copyright Theodore Kilgore <kilgota@auburn.edu> April, 2004. This README
revised August 27, 2006.

(Everything in libgphoto2/camlibs/mars is LGPL-licensed, including this README; 
see any of the source files for a more complete statement of the license.)

INTRODUCTION

This driver is for a camera which uses the Mars MR97310 chip. I understand 
that there are several of these. Mine is an Aiptek PenCam VGA+ (Vendor:Product
ID 0x08ca:0x0111). The interface is proprietary, and these cameras are 
supported commercially only in Windows.

FEATURES OF THE CAMERAS

The first MR97310 camera which I encountered was the Aiptek PenCam VGA+,
a "budget" camera with resolution settings of 640x480 and 320x240.  
This camera and the other MR97310 cameras can also be used as webcams 
(not supportable here; would require a kernel module) or to make a "video 
clip." Some of the other cameras automatically will run in compressed mode 
when shooting clips, but on the Aiptek it is optional to compress clips.  
Clips download nicely on all these cameras as a succession of PPM files. 
The compression method (optional for the Aiptek camera) is proprietary and 
not obvious. With recent progress, it ought to be usable. However, the 
adventurous and persistent are hereby encouraged to play with it some more. 

09/12/05: Decompression sort of works, now. Thanks to Bertrik Sikkens 
for the basic algorithm, and to Michel Xhaard for testing my additional tweaks. 
With some of the cameras it is possible now to get decent photos in compressed 
mode, at least some of the time. For this, the camera seems to function best 
at outdoor use. 

Update 08/28/06: Decompression algorithm much improved, after much trial 
and error. I would say it is now somewhere between 90% to 100% good now. Seems
to work almost perfectly outdoors and in strong light. Works even better at low 
resolution settings, that is, 352x288 or lower. 

The camera uses a configuration "block," as do the sq905 cameras. However, 
here the information can be used to run options such as gphoto2 -p 3 and 
gphoto2 -p 3-5. The OEM software provided with the various cameras does not 
take advantage even of the mentioned abilities. With the OEM driver, one has 
the choice either to download all photos, or none. If all are downloaded, then 
thumbnails are created. The user can then do previews and decide what to save. 


STATUS NOTES ON SUPPORTED CAMERAS (7 Feb. 2006, revised 28 Aug. 2006)

First, a special note: On many of these cameras, the LED will read "PC" when 
the camera is hooked to a live USB connector. It seems locked in this position.
But all of the cameras which do this, which I have tested, will come up with 
all of the other camera button commands if one runs any gphoto2 option which 
accesses the camera. Consequently, one can use the camera thus tethered, 
without any battery in it, to shoot and download photos. The photos will die
soon if the camera is unhooked without a good battery in it, though, because 
the camera uses volatile memory for its data storage. 

The only problem with using any of these cameras is the compression codec. 
Bertrik's decompression algorithm seems basically correct, but it has a problem 
with leaving diagonal color artifacts, a problem which can be severe in bad 
lighting conditions, especially if there are lots of dark colors in the photo. 
Those cameras with 352x288 max resolution instead of 640x480 do better, and the 
Argus DC-1620 does better in poor light than does the Aiptek Pencam VGA+.
I have recently been able to alleviate these problems to a great extent, but 
not completely. Also, not all of the cameras seem to perform equally well 
in compressed mode when used to shoot similar photos under similar lighting 
conditions. After the tweaks I have added as of August 2006, though, the
situation with compression mode is improved quite a bit.

Here is a report on the cameras which I own. I can not say anything 
about the others unless their performance in compressed mode is reported to me:

Aiptek Pencam VGA+: Compressed mode is very sensitive to bad lighting, 
especially when there are dark colors in the image (08/27/06: better now). 
The camera also will refuse to shoot both in compressed and in uncompressed 
mode if the light is very bad (indoors, in the evening) and that is probably 
all for the best. 

Argus DC-1620: Compressed mode only. No uncompressed photos. The compressed 
mode works pretty well, though. Outdoor photos are pretty good, and if you are
willing to put up with a cheap, compressed-mode-only camera it might even be 
worth your money. The camera does have some problems in bad light, but not so
severe as with the Aiptek Pencam VGA+. Camera does have a flash-light which can
be turned on in bad light. The camera will then decide if it wants to use it. 

Sakar Digital #77379: Also compressed mode only. Seems to work pretty well. Has 
a very high cutoff threshold and will not take photos in the evening, even if 
one points it at a bright monitor screen. Color mapping is cruddy, though, even 
running in uncompressed mode.  

Philips Keychain and INNOVAGE Mini Digital: These seem to be clones, even 
having very similar cases. They will do max resolution 352x488. But for what 
they are they work very well. It seems that these shoot clips in compressed 
mode (no matter if you otherwise turned compression on, or not), but at the 
resolution settings these cameras use the decompression works nicely, too. 

Argus QuickClix: Compressed mode only. The compression algorithm is different 
from the compression algorithm in the other known Mars cameras, too. I have 
no idea how the compression algorithm works, either. Thus, this camera is a 
paperweight unless someone figures out how to decompress the data. Don't buy 
one unless you are adventurous, patient, and want to help out. That's why it 
is listed as DEPRECATED. 

SPECIFIC WARNING REGARDING ARGUS QUICKCLIX

For the Mars cameras, all data for raw photos begins with a signature. The 
uncompressed photos begin with FF FF 00 FF 96 64 00, and raw photos using the 
compression which is solved begin with FF FF 00 FF 96 64 50. If you get a 
camera in which the raw data begins with the signature FF FF 00 FF 96 64 20 
then your camera uses the same compression algorithm as the Argus QuickClix. 
That compression method is as yet unknown; a camera using it is a paperweight. 

Finally, one can not distinguish an Argus QuickClix from an Argus DC-1620 by 
appearance. From the outside they are identical. Also they and several other 
cameras use the same USB Vendor:Product number and do not give any 
identification string after they are connected, either. So, unless the new 
compression algorithm is unlocked, there is a real problem here. 


USABILITY OF DRIVER WITH GUI FRONTENDS

The camera library presented here seems to work with gtkam as a frontend. To 
use gtkam for the first time with any camera, you must choose the camera. 
For this purpose, after starting gtkam click on "Camera." Then choose 
"Add Camera." Then "Detect." Click on the name of the camera to get photos. 
Gtkam creates its own thumbnails for cameras which do not offer them. These 
cameras do not offer thumbnails. 

Digikam as a frontend works, too. But for some reason 
digikam seems unable to display thumbnails from this camera. Anyone who knows 
what the problem is here, please let me know. 

Flphoto works well, too, with no obvious glitches. Flphoto is also willing to 
create thumbnails and does so without any tweaking. 


SAVING RAW FILES AND USING THEM LATER (09-23-06)

All raw photos downloaded from the camera come with a signature and a header 
which is 12 bytes in length. This header has always been retained if the
photo is saved in raw format. The last few of the bytes in this header seem to 
pertain to things like brightness and color balance (not usable information, 
at this time, but may be in the future). The first bytes are always

FF FF 00 FF 96 64

and the next byte (as received from the camera) is either 00 (if the image is 
uncompressed) or is 50 if the image has been subjected to the "standard" 
MR97310 compression or is 20 if the image has been subjected to the totally
unknown Argus QuickClix compression. 

Thus the header of any given image as it comes from the camera tells us in 
byte 6 of the header whether the image is compressed or if compressed then
which algorithm has been used. That information uses the most significant nibble 
of the "compression" byte. But if we do not do something, the pixel dimension of 
the photo to be obtained from the raw file is not recorded. As the camera also 
codes this information in one nibble, we place that nibble here, too:

Original raw signature 		pixel dim. 	Saved as 		Comp.
FF FF 00 FF 96 64 00		176x144		FF FF 00 FF 96 64 00	no
				352x288		FF FF 00 FF 96 64 02	no
				320x240		FF FF 00 FF 96 64 06	no
				640x480		FF FF 00 FF 96 64 08    no
FF FF 00 FF 96 64 50		176x144		FF FF 00 FF 96 64 50	yes
				352x288		FF FF 00 FF 96 64 52	yes
				320x240		FF FF 00 FF 96 64 56	yes
				640x480		FF FF 00 FF 96 64 58	yes

(similar will happen if compression code is the bad 0x20, as well)

With this small change, the raw file now contains all information within 
itself that is needed for processing it. 
				
				
FURTHER DETAILS

Further details are given in "protocol.txt". These details have been obtained 
through trial and error and are intended solely to meet the problems of 
compatibility in other than a Microsoft Windows (trademark) environment. 

WARRANTY?

Absolutely none. Remember, I did not sell you this software. I have written 
this driver for my own edification and in the sincere hope that it might help 
you to use of your camera. Please see also the warranty clauses 
in the LGPL license. 