1 /* This is the README file for libgphoto2/camlibs/digigr8. This README is an
2 * integral part of the libgphoto2/camlibs/digigr8 library source code and is
3 * distributed with that source code under the LGPL license, a copy of which
4 * license may be seen in the head directory of libgphoto2, in the file
6 * Original of this file copyright Theodore Kilgore, 12/05/05.
12 The cameras supported here have a controller chip from S&Q Technologies.
13 They have USB Vendor:Product number 0x2770:0x905c. These cameras are cheap
14 and basic. Their functioning resembles that of the cameras supported by the
15 sq905 camera library, but is a bit different. More recently (07/11/2007) I
16 have discovered a camera with Product ID 0x9050 which will also function with
17 the same driver library. A more specific description of this camera can be
18 found in README.9050. Still more recently, several cameras with USB ID
19 0x2770:0x913D also came onto the market. These cameras also can be made to
20 function with the same code base, in spite of some differences. They are
21 more specifically described in README.913D.
23 The first camera which I knew of with USB ID 0x2770:0x905C was the Digigr8 from
24 RadioShack. Hence comes the name of this camera library. Several more cameras
25 have since been reported, including one which has the same make/model painted
26 on the plastic case as that of a camera which previously used an sq905 chip
27 and used the sq905 Vendor:Product number instead of this one. SQ Technologies
28 seems to have discontinued the SQ905 and the SQ905C is apparently its successor.
30 For information about additional cameras with the same USB ID, I am totally
31 dependent on reports from users and testers. If you have another 0x2770:0x905c
32 camera and want it to work and it currently does not, then I will be very glad
33 to hear from you. Saying this a different way: further progress with your
34 camera will depend upon your input. If on the other hand your camera does work
35 and is not explicitly listed, I would still like to know about it for the sake
36 of completeness. I will give it an explicit line listing in library.c and I
37 will credit you as the finder of the camera, in the ChangeLog file.
40 WHAT CHIP IS ACTUALLY IN THESE CAMERAS?
42 I do not know. I did not take one apart to look inside. (update) Someone has
43 reported to me that he did take his camera apart, and it really is an SQ905C
46 WHAT FEATURES DO THESE CAMERAS HAVE, AND WHAT DOES THIS DRIVER SUPPORT?
48 FEATURE LIST SUPPORTED (Y/N/Part)
49 -- USB connection to computer
50 -- High resolution 640x480, uncompressed Y
51 -- Low resolution 320x240, uncompressed Y
52 -- High resolution 640x480, compressed Y
53 -- Low resolution 320x240, compressed Y
54 -- Ability to "switch" resolution between pictures Y
55 -- Ability to download all pictures on camera Y
56 -- Ability to download the first k pictures, where
57 k is less than the number on the camera Y
58 -- Ability to download individual photos Y (faked, but works)
59 -- Shoot a frame and save image to computer Y
60 -- Internal battery, which recharges through the USB port (some models)
62 -------------------------------------------------------------------------
63 The following things can be done with button-pushes on the camera:
64 -------------------------------------------------------------------------
65 -- Frequency filter for use in artificial light. Can be set
66 to cancel 60hz or 50hz interference.
67 -- Delete all, delete last, resolution setting, compression mode setting.
68 -- "Clip" mode will shoot three frames. The camera "sees" these frames as
69 ordinary photos. Also the photo counter on the LED counts them.
70 -- "AVI" mode shoots until the shutter button is released, or until the
71 camera is full. The photo counter on the camera does NOT count the
72 AVI frames as separate items, but thinks all of the frames are part
73 of one photo. Otherwise, the camera in fact sees the frames as
74 ordinary photos, so gphoto2 will give the actual count of all frames,
75 no matter whether photos or part of an AVI clip. Accordingly, gphoto2
76 will download the AVI frames as if they were ordinary photos and will
77 sequentially number the frames in the course of numbering the photos
78 which come out of the camera. The user can easily create a movie from
79 the AVI frames, using an animation program, such as the "animate"
80 command from the ImageMagick package. The default resolution for AVI
81 frames is always 320x240 regardless of the resolution setting chosen
82 for still photos. AVI mode will use compression if it otherwise
83 happens to be turned on.
87 The 0x2770:0x9050 and 0x2770:913D cameras differ from the above description in
88 some particulars. Please see the respective README files for details.
90 Almost all known cameras supported by the camlibs/digigr8 have a 640x480
91 high-resolution setting and a 320x240 low-resolution setting. If your
92 0x2770:0x905c camera uses another resolution setting, then it might still
93 work. There is some similarity with the sq905 cameras, and I kept that part
94 of the code here. Specifically, if the camera has 352x288 and 176x144
95 resolution settings, these might work but are not tested (Note added July 2007:
96 the code for 352x288 _does_ continue to work; see below). If your camera does
97 not work due to unknown resolution settings, then the new resolution settings
98 need to be listed in digigr8.c in digi_get_picture_width (). Please report any
99 such problem. I will ask you to run a gphoto2 command in debug mode and we can
100 easily find the information we need -- which information, understand, I do not
101 possess unless you share it with me.
103 The pictures obtained on the uncompressed settings can often be superior to
104 those obtained using the software which came with the camera, but not
105 always. Generally, considering that they are cheap, low resolution cameras,
106 these cameras give relatively good pictures.
108 The digigr8 cameras can also function as webcams, but that is outside the
112 HARDWARE LIMITATIONS AND CONSTRAINTS
114 The SQ905C chip, like the SQ905 before it, is a minimalist controller chip; if
115 any of its functionality at all were removed, it would probably be impossible to
116 use it to run a digital camera. To program around the limitations of the chip,
117 therefore, is a special challenge. Here are some examples.
119 1. The manufacturer's driver will do nothing but to download all photos
120 on the camera, and display them, keeping temporary copies in C:\TEMP, to be
121 deleted when the camera access program is closed. After downloading everything,
122 then, the OEM program allows the user to "select" and to "save" any or all of
123 the photos which have, in fact, already been downloaded (indeed the displayed
124 "thumbnails" came from the files in C:\TEMP, too). Now, gphoto2 does not
125 operate thus, has preconceived notions about how any respectable camera should
126 act, and regards such a primitive camera controller chip as an untamed beast.
127 Thus, many of the gphoto2 functions will not work unless, through a bit of
128 fakery which involves downloading data and throwing it away and on some
129 occasions resetting the camera, this primitive behavior is somewhat improved.
130 That all has to be done in the driver, with fakery invisible to the user. These
131 remarks apply not only to getting thumbnails, but also to many other gphoto2
132 options as well. See item 2.
134 2. The camera's data storage provides only sequential access, not
135 random access. In other words, it acts as though it were a tape drive
136 instead of a disk. Worse, it's like a tape drive with no fast forward and
137 no rewind controls. The constraints which this places are obvious. It means
138 for example that to download all the photos on the camera to display thumbnails
139 requires the camera to be reset afterwards, because that is the only way to do
140 the "rewind" required before any of the photos can be accessed again. It also
141 menas that "gphoto2 -p 2" would NOT download the second photo on the camera,
142 unless the support for it is so written as to download the first photo, then
143 the second photo, and to process only the second one, having consigned the
144 data from the first photo to /dev/null. The camera simply cannot do better.
145 The gphoto2 -p 2 command option does work, of course, but only because the
146 necessary jury-rigging has been built into the download function.
148 3. Considering the way the communication protocols of these cameras
149 seem to work, it would seem nearly impossible to copy any data to the camera
150 for storage and transport. The camera clearly does not have files on it,
151 only data addresses. And the camera does not keep time. For similar
152 reasons, it would also seem impossible to delete a photo from the camera by
153 action of software on the computer. The camera itself supports two choices for
154 deletion: delete the last photo taken, or delete all. Each action is
155 performed by an appropriate sequence of button pushes on the camera.
158 WHAT GUI FRONTENDS DOES THIS CAMERA LIBRARY SUPPORT?
160 Gtkam seems to work well for me with this library, and also flphoto. Some of
161 the other various frontends do not seem to work quite so well for me. But one
162 of them may work nicely for you, and you are hereby encouraged to try whichever
163 one is your favorite. If you want to use either gtkam or digikam, you are
164 encouraged to read the camera's manual (in gtkam, right-click on the name of
165 the camera in the left panel, after starting the program and having chosen the
171 1. The program is set up to put out pictures in PPM or raw format. The OEM
172 program offers JPEGs. If the user desires JPEG output, then that can easily
173 be done on Linux, using other software which exists independently from
176 2. As of 01/20/2008, all raw files downloaded from these cameras will
177 have a "footer" of length 16 bytes. This footer consists of the line from the
178 camera's allocation table, which gives some information about the photo. The
179 information includes a code for the resolution and compression setting
180 and some information which may be useful in the future relating to color and
181 lighting. Unfortunately, the meaning of the color and lighting information is
182 not well enough understood to be useful at this time, but it may be useful in
183 the future, so why not preserve the information?
185 3. The gamma setting (actually seems to be one over gamma) used for
186 the construction of PPM image files has been obtained by trial and error. It
187 seems to work very well for outdoor pictures, but the setting is a
188 compromise between what happens with outdoor photos and what happens with
189 indoor photos. Conceivably, the program could support a choice between two
190 or more gamma settings, optimizing for different conditions.
193 4. A still-experimental postprocessing routine is added, to provide
194 some sharpening and color correction for different lighting conditions. The
195 routine can easily be turned off if one wishes, and because it is
196 experimental you may so wish. To disable it, just comment out the line in
197 get_file_func ( ) in library.c where the function digi_postprocess ( ) is
198 called. Then do "make install" to install your change.
201 5. An experimental program for processing raw files into finished photos
202 is available now, in gphoto2/trunk/playground/raw_converters/sq_raw_converter
203 Please try this program. If the results are good, I will incorporate the
204 routines used there directly into libgphot02/camlibs/digigr8. I like the
205 results, but they need testing.
208 6. The "High Compression" setting uses an unpublished compression
209 algorithm. However, after serious effort the decompression seems to work
210 pretty well. There are at this time (01/20/2008) no known issues with it.
212 7. Please get back to me with reports about other SQ cameras (any cameras
213 with Vendor number 0x2770), with their specifications (what it says in the OEM
214 manual about resolution and number of pictures, as well as make and model, and
215 whether it works or not with any libgphoto2 driver or not, would be enough),
216 and with a log file if it seems it is supposed to work but there are problems.
219 A NOTE ON CAPTURE AND ON CHANGING THE RESOLUTION SETTING FOR CAPTURE
221 These cameras will perform "gphoto2 --capture-preview" which means, to shoot a
222 frame and download it to the computer immediately. On the 0x9050 camera, the
223 same USB command which trips the shutter will simultaneously delete all frames
224 on the camera. On the 0x905C cameras, capture works, but will not affect whatever
227 The default resolution setting for capture with all these cameras is 320x240.
228 For those cameras which will do 640x480 resolution in still photo mode, there
229 is a tweak which can cause the camera to do the
230 capture at 640x480 as well. It is as follows:
232 Look through the code in camlibs/library.c for the capture function. You will
233 see a USB command in which the digit 0x1440 appears. Change that to 0x2840 and
234 re-compile and re-install. It is also possible to get 160x120 resolution, but
235 that is not so interesting. Evidently, the "40" means to do capture, and the
236 previous two digits are the resolution setting in hexadecimal, with the final
237 "0" removed. For example, 640=0x280 -> 0x2840 and 320=0x140 -> 0x1440 (which,
238 again, is the default setting). I am not sure what would happen if the
239 resolution setting here is too high for the camera (the known 0x9050 camera
240 will only do 352x288 at max resolution in still mode, for instance). Therefore,
241 this tweak is not implemented. However, it does work for me with those cameras
242 for which it works. It should be repeated, too, that this tweak is not
243 documented by any manufacturer and is not available in the OEM driver for any
249 Absolutely not. No warranty. Never. Not responsible for any actual
250 or potential damage or consequences to anyone or to the equipment of
251 anyone for using this program, whether the alleged damage or alleged
252 consequences are claimed to be real, imaginary, direct, collateral,
253 for pain and suffering, or are claimed to be inflicted upon any
254 "third party" who is not the user or installer of the program. The
255 program has been written for my pleasure and to broaden and deepen
256 my knowledge of computer hardware and software. The program has not
257 been written with the immediate expectation of financial gain or
258 profit on my part, nor has it been commissioned for pay. It is
259 presumed that any end-user of this program will have access to the
260 source code of the program and can judge for himself or herself
261 whether he/she wishes to use it or not, or can consult someone with
262 appropriate expertise to make such a judgment.
267 (revised 12/29/05, 03/28/07, 06/25/07, 07/16/07, 07/23/07, 01/21/08, 01/22/08)