******************************** **** **** **** Bilderspur README **** **** **** **** **** **** (c) Gunter Ohrner **** **** **** ******************************** Licence ======= Bilderspur is (c)opyright 2006-2007 by Gunter Ohrner (gunter _(@)_ ohrner.net) and is Free Software licenced under the GNU General Public License version 2. Please see the file "GPL_V2" for details. What is Bilderspur's purpose? ============================= Bilderspur allows you to use the virtual globe application Google Earth as some kind of "photo album deluxe". It reads a batch of JPEG images which contain GPS coordinates (normally the location where they were shot) and generates a KML or KMZ input file which can be loaded into Google Earth. GE will then display an icon or a thumbnail preview of each image at the corresponding location on the globe, allowing you to view the full resolution image by simply clicking at the icon / thumbnail. This way you'll never forget anymore where an image was taken, and its a perfect way to document travels or motorcycle / bicycle tours. In fact I wrote Bilderspur to document a bicycle tour from Aachen in Germany to Paris in France. Ussage Example ============== ./bilderspur.py -i /var/tmp -W 750 -z -o ParisTour.kmz *.JPG This will generate a compressed KMZ file with contained thumbnail images and relative references to the local JPEG files. The thumbail images will be prepared in the directory /var/tmp and will remain there. (They are not deleted automatically.) Invoke ./bilderspur.py -h to see the full list of options. What are the prerequisites to use Bilderspur? ============================================= First of all, you need images with encoded GPS location information, of course. There are special digital cameras which contain a GPS receiver, but you can also get this information using a standard digital consumer camera and a stand alone GPS receiver which can record a track. This is the way we chose for our bycicle tour. We used a GPS receiver from Garmin which recorded the whole tour and allowed to export it as a GPX file. We then used the program gpscorrelate write the correct GPS position into the JPEG image files. gpscorrelate uses the image's timestamps and the time recorded by the GPS receiver to match the images with the GPS position information. The images post-processed by gpscorrelate can then be used directly as input images for Bilderspur. For this all to work, it is an absolute requirement to either ensure an accurate setting of the digital camera's clock or to post-process the images so that they contain the correct time stamps. As we had four cameras, none of which had its clock synchronized with a reliable time source before we started our tour, we used Cubbi's HolidayPhotoViewer to fix the image's time stamps. Finding the correct time offsets was probably the hardest part of the whole procedure. ;) If you use several digital cameras and forget to synchonize their clocks to a radio controlled clock in advance, it's extremely adviseable a) not to change the relative differences of the camera's clocks - ie. do not change the clocks while "on tour" - and b) to shoot a "synchronization photo", that is, photograph an easily recognizeable scene with all cameras at the same time, so that the time stamp differences of these photos tell you the time differences between the camera's clocks. The concept of clustering images ================================ Bilderspur can automatically group images which have been shot at nearly the same location under one thumbail icon. This greatly helps to avoid cluttering the map at places where you usually shoot many images, like town centers, historic places and picknick sites. These groups are called "clusters" and are represented by a single icon or thumbnail image. If you click the icon, the actual images will be shown in a list. Bilderspur accepts several parameters which control how clustering is to be performed, if at all. You can specify how close images must be together to be clustered, how many images a cluster may contain before a new one is forcibly created and the minimum distance between two clusters. (If two clusters are too close, they are shifted a bit to fulfill the minimum distance constraint.) What are the -e and -E switches used for? ========================================= Sometimes you might want to generate KML or KMZ files which link to images stored in an already existing online photo album or similar. Provided that you know Python you can fully customize the URLs generated for thumbnail images and the HTML text used to display the image after clicking the thumbnail by using the -e and -E command line switches - without changing a single line of code in the bilderspur script. Both parameters take a python expression: -e The expression given to "-e" generates the URL used to refer to the thumbnail images. The expression must accept three arguments, the first being the full filename (with leading directory part, if any) of the temporary file containing the thumbnail image; the second parameter being a list of all images in the cluster represented by the thumbnail and the last argument being whatever you specify as the "-u" parameter. The last parameter will be the value None if you did not specify the -u command line parameter. The list of images actually is a list of ImageInfoRecord objects which contain lots of relevant information about each image, including the complete and decoded EXIF header tags. The default behaviour of -e equals the following lambda-expression: lambda name, images, url: iif(url == None, \ name, \ '%s%s' % (url, os.path.basename(thumb_file_name)) -E The expression given to "-E" returns a complete HTML code fragment which is then used to display the image in the KML placemark's description panel, after the icon / thumbnail has been clicked. This expression is evaluated once for every single image, instead of one per cluster. This expression must accept four argument, the ImageInfoRecord describing the current image, the HTML width and the height settings given as "-H" and "-W" command line arguments (may both be None) and the as the fouth argument string given to the command line parameter "-U". The default function used to generate the HTML description text is rather complex and would result in a rather longish lambda expression, but it could be represented as one. I'll later give an example at this place. Used Modules ============ Bilderspur uses pyKML (http://sourceforge.net/projects/pykml) and EXIF.py by Gene Cash.