MARS MR97310 STILLCAM DRIVER
Copyright Theodore Kilgore <kilgota@auburn.edu> April, 2004. Latest revision
of this README March 15, 2008.

(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 cameras which use the Mars MR97310 chip, frequently found in 
budget cameras. 

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 by gphoto2; 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 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. 

Update 08/21/07: Decompression issues essentially resolved, for the "0x50"
compression algorithm. However, another, different compression algorithm is 
also used in some of the cameras. 

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 from temporary image files in C:\TEMP. Thereby, the user 
can decide what to "save" in some more permanent place. 


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 permit this 
lock to be cleared if one runs any gphoto2 option (for example, gphoto2 -n or
gphoto2 --summary will clear the "PC" lock very nicely), and after this 
everything on the camera can be made to work, just as if the camera were not 
tethered. 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 is reported to me. This especially 
applies in case that the camera uses compressed mode, since there are two 
compression algorithms in use and we can handle only one of them to any extent
at all. 

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. 640x480 and 320x240 resolution.

Philips Keychain, INNOVAGE Mini Digital Vivitar 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. Probably the CD302N and the Pixart Gemini are the same, too, but I do not 
have direct experience. Trust SpyC@m 100: Reported as working, seems from 
manufacturer's description to be another camera similar to the Philips KeyChain. 
Furthermore, www.trust.com (the manufacturer) says that the Trust SpyC@m 100s 
is the same camera inside, too, so it is also presumed to work. 


Sakar Digital 56379 "Spy Shot": Another keychain camera, but also contains a 
microphone and will capture sound. There is a toggle switch on the camera, 
which is labelled "photo" on one side and "voice" on the other. If the 
"voice" toggle is chosen, then actual recording is turned on and off with a 
press of the shutter button. The output is kept in the camera. This feature 
is supported as of 04/07/07; the audio output may be downloaded as a WAVE file 
with the usual options gphoto2 -P or gphoto2 -p (number). Note: the option
--capture-sound and the various "audio" options are _not_ supported. In any 
event, the usual options do make sound files accessible in a GUI environment.

ION digital camera: Compression optional. High cutoff threshold for what the 
camera considers bad light; will not take photos indoors, sometimes, even on a 
bright day. Color mapping is unspectacular. Camera case looks like there is a 
microphone on it, but there isn't.

Sakar no. 1638x CyberPix: Usable in uncompressed mode. Compression algorithm 
appears to be the same as that for the Argus QuickClix (see next listing) and 
is unknown. WARNING! When turned on the camera comes up in compressed mode !!!
The user can change this by hand by choosing "nP" in the camera's LCD. Do this
before you shoot photos, else the photos will be useless !!! 

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. 

The Sakar CyberPix also uses this unknown compression, which is turned on by 
default. The user must turn it off in order to get usable photos. See notes
about this camera, above. 

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. Sound files are "seen" by name, with no 
thumbnail, and can otherwise be selected, deleted, or saved, just like image 
files. The default option in gtkam is to save to $PWD. I like that. You can
change that behavior if you want, I understand. 

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. Sound files are handled 
pretty much as in gtkam. You will get a whine on saving, that the file cannot 
be put into the "album" but it will be saved to the chosen directory 
nevertheless. Flphoto will not automatically save in $PWD but instead will 
open the directory it used last time. I hate that. Someone out there must love 
that behavior, though. Or it wouldn't be set up that way. Otherwise, flphoto
is really slick. 


SAVING RAW PHOTO 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, thus:

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. If 
you would like to see this file and it is not included for some reason in a 
"released" version of libgphoto2, then it can be found in the SVN source 
repository.

THE mars_white_balance() FUNCTION

This function first of all does what its name implies. It also re-computes a 
better gamma factor for the individual image, based upon internal 
characteristics detected in the image, and does color enhancement. If you do 
not like what it is doing, then you can turn it off by commenting out the line
in library.c where it is called, but I expect that the user will not want to 
do that, because it seems to me that the image quality is much, much better.


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, which do not appear to me to conflict with my own statement here. 