Readme for PicaJetToDigiKam v0.1.

Copyright 2009 by Toke Eskildsen, http://ekot.dk, te@ekot.dk.

This program is freeware, Open Source (mail me for details or hunt my webpage)
and under the do-whatever-you-like-as-long-as-you-don't-hold-me-responsible
license. It is, after all, just the result of a few nights hacking.

PicaJetToDigiKam requires Java 1.6.

=== Introduction ===

The sole purpose for this program is to extract information from PicaJet FX and
insert it into digiKam 0.10. If you are not a PicaJet-user and do not plan on
using digiKam, you have no use for this program. If you are a PicaJet user, do
read on.

Now, why do we want to do this data transfer?

PicaJet FX (http://picajet.com) is a payware program that has a rather slick
interface and works okay for tagging. It is also crash-prone, does not scale 
well (at least not to the 50.000 images I have) and updates have been very
slow the last couple of years.

Time to move on. As an old PicaJet-user I like digiKam, so you might also want
to give it a shot. The beauty of digiKam is that with KDE 4, it now runs under
Linux & Windows (and OSX?).


=== What does it do exactly? ===

It merges the tag-tree, the tagging information, author, caption and rating
from PicaJet FX into an existing digiKam database.

PicaJet can do some other stuff with images, called QuickEdit that has to do
with adjusting image properties, such as rotation, brightness and so on. These
adjustments are not migrated.


=== How to use the migrator ===

The migration of the data involves some simple manual steps, what I will walk
you through (pun intended). The migration only adds data, so it can be repeated
if you happen make some extra updates in PicaJet before abandoning it forever.

1) Export the PicaJet data
   This step changes none of your existing files.
1.1) Open PicaJet FX
1.2) Choose File | Export | Entire Album as XML...
1.3) Save the dump as pj.xml in the PicaJetToDigiKam folder

2) Set up digiKam
   This step ensures that your digiKam-installation is aware of all the images
   that you have managed with PicaJet. It is a necessary step as only already
   existing images in digiKam will be updated with the data from PicaJet.
   This step might add images to your digiKam database.
2.1) Download and install KDE4 from http://windows.kde.org/ - select digiKam
2.2) In digiKam, enter Settings | Configure digiKam... and add all the folders
     that contain images that you have tagged in PicaJet. Don't worry if the
     paths are not presented in exactly the same way as in PicaJet:
     PicaJetToDigiKam does fuzzy matching, if an exact match is not available
2.3) Create at least one Tag and assign it to at least one Image.
2.4) Quit digiKam

3) Export digiKam images and tags
   This step changes none of your existing files.
3.1) Download SQLite Database Manager (http://sqlitebrowser.sourceforge.net/)
3.2) With SQLite DM, open the digiKam database - it should be located in the
     base folder you selected when installing digiKam
3.3) Choose File | Export | Database to SQL file
3.4) Save the dump as dk.sql in the PicaJetToDigiKam folder

4) Merge the data
   This step changes none of your existing files.
4.1) Open a command prompt and navigate to the PicaJetToDigiKam folder
4.2) Enter "java -jar PicaJetToDigiKam.jar -p pj.xml -d dk.sql newdk.sql"
     The file newdk.sql should be created. It will contain an update to your
     digiKam database with a merge of the tags from both PicaJet and digiKam.
     The update will do a full replacement of the existing tags in the digiKam
     database, so make sure you apply it before you do any more fiddling in
     digiKam.
4.3) Close the prompt

5) Import the new data into digiKam
   This step updates your digiKam database, so beware! Please, please, please
   make a backup of the database first!
4.1) Make a backup of your old digiKam database
4.2) In SQLite Database Manager choose File | Import | Database from SQL file
4.3) Open the file newdk.sql
4.4) Select "No" when asked if you want to create a new database
4.5) Exit SQLite Database Manager
4.6) All done, have a beer (or start digiKam and tag along)


=== Gotchas & caveats ===

DigiKam does not have an explicit author, so if an author is specified in a
PicaJet-dump, it will be created as a tag under the tag "Authors". If the tag
"Authors" does not exist at the root, it will be created.


=== Trobleshooting ===

Send me an email at te@ekot.dk. Describe in detail what happened and attach the
output from the migration attempt. If they are not too personal, also attach
your dumps from PicaJet and digiKam. Please ZIP (or TAR/GZ) the files.