path: root/doc/man/digitaglinktree.1

.\"             -*-Nroff-*-
.\"
.TH digitaglinktree 1 "16 Aug 2006 " " " "Linux User's Manual"
.SH NAME
digitaglinktree \- Export tag structure of photos in digikam to the filesystem.
.SH SYNOPSIS
.B digitaglinktree 
.B -r\fI rootdir\fR

.B -l\fI taglinkdir\fR
|
.B -A\fI archivedir\fR

.B -d\fI database\fR

.B [-H|-f|-a|-v|-C]

.SH DESCRIPTION
.B "digitaglinktree "
will create a linktree for all photos in a digikam database that have tags set
on them. Tags (like eg. "family", "events", ...)  are used in digikam to create
virtual folders containing images that all have one or more tags assigned. 
Please note: Photos that have no tags at all assigned are silently ignored by
this script. The program will not modify or even touch your original photos
managed by digikam. 
 

The script can be used in two ways: If you call it using
Option  -l \fItaglinkdir\fR  the script will create the user specified 
directory  \fItaglinkdir\fR and inside this directory it will create sub
directories for digikam tags  set on the photos. Inside these subdirectories it
will finally  place symbolic or hard links  (see -H) to photos having the tags
in question.  As a result you will see the tags of your photos as folders and in
these folders  you will find links to your original photos.  


In this way you can access the collection of all images that share a certain tag
by changing directory to the folder with the tags name created by this script.
This allows you e.g. to run JAlbum a photo album software that needs to find the
pictures to be put into a web album in the filesystem because JAlbum cannot
access digikams virtual folders directly.


The second way of calling this script is the so called archive-mode by setting 
option  -A \fIarchiveDir\fR.

Archive mode is thought for people who want to archive  tagged photos
independently of digikams root directories and the photos therein.  This way you
can put your photos and their tag structure in eg. a tar archive and send it  to
a friend, who can look at the photos  via their tag structure. In this mode the
script creates the directory given as  parameter to -A and in this directory two
more subdirectories. One named  Photos and a second named Tags.  The Photos
directory contains hard links  to your original photos, and the Tags directory
contains a subdirectory for each  Tag used by any of your photos. Inside this
subdirectory there are links (either symbolic or hard links) to the files in the
Photos directory. This way the archive  directory needs nearly no additional
space on your harddisk and you have an archive that  allows you or a friend to
easily look at the photos tag structure. 

Another benefit from using this script is that you have kind of a backup of your
tag settings for all of your photos. The backup is simply the directory
structure containing links to the original images that wear the tags.
This could become important if
for whatever reason the digikam.db file gets corrupted or even lost.

.PP
.SH "COMMAND\-LINE OPTIONS"
.TP
\fB \-r \fIrootdir\fR 
\fIrootdir\fR denotes the digikam base directory containing all your photos.

.TP
\fB \-l\fI taglinkdir\fR
Parameter \fI taglinkdir\fR denotes a directory in which the tag structure of 
all your photos stored in 
rootdir will be exported to by creating subdirectories for each tag and placing 
symbolic links in these subdirectories that point to the original photo wearing
the tags. If calling the script with option  -l\fI taglinkDir\fR you also have
to  specify options -r  \fIrootdir\fR as well as -d \fIdatabase\fR.

.TP
\fB \-A \fIarchivedirectory\fR 
\fIarchivedirectory\fR denotes a directory into which the script will export the photos  and their tag
structure. -A has to be used together with option  -r  \fIrootdir\fR as well as 
-d\fI database\fR else the script will terminate.  Inside the archive  directory
the script will create a Photos and a Tags directory. It will put hard links in
the  Photos directory  that point to your original photos. By using hard links
you are independent  of changes in your digikam root directory but on the other
hand you are limited to one filesystem.  So the directory given by 
-r \fIrootdir\fR and the directory specified for -A \fIarchivedir\fR have to be  one
the same filesystem. The Tags subdirectory will contain links to the files in
the Photos directory. This way you have one archive directory that is completely
self contained. You can tar it, send it to a friend or  just put it somewhere
for archivel or backup purposes. Usually only those photos will be archived that
have a digikam tag set on them. By using option -C however you can perform a
complete archive. See -C for more infos. 

.TP
\fB \-d \fIdatabase\fR
\fIdatabase\fR is the complete path including the filename to digikams photo database which
usually can be found in digikams root directory. The files name  is usually
digikam.db .

.TP
\fB \-C\fR
When the script is called with option -A \fIarchivedir\fR only those photos
will be archived (by placing links) in the Photos subdirectory of
\fIarchivedir\fR that have at least one digikam tag set. By setting option -C all
photos will be  archived to  \fIarchivedir\fR no matter if they have a tag set
or not. Note: This only changes the contents of the Photos  subdirectory not of
the Tags subdirectory in the \fIarchivedir\fR directory.

.TP
\fB \-a \fR
By default the script will try to create relative symbolic links from the
directory  \fItaglinkdir\fR  set by option -l to the photo files under  
\fIrootdir\fR given by option -r. Using this option will result in  absolute symbolic
links beeing created instead of relative ones.

.TP
\fB \-H \fR
By default the script will create soft (symbolic) links from the Tag-Tree to the 
photos. By setting option -H the script will use hard links instead. Please note 
that hard links can only be created inside one filesystem. So your photos and the Tag tree
have to be one the same filesystem. If not you will see a warning about this problem and the script
will not run.

.TP
\fB \-f \fR
In digikam photos can have hierachical tags (tags that have subtags). In this case 
digitaglinktree would by default add a directory for the tag and a subdirectory for 
each of the subtags of this tag. By setting \fB \-f \fR a subtag is treated like a 
regular tag just as its parent tag so digitaglinktree will create all subdirectories 
for tags and subtags at the same level independent of the tag - subtag hierarchy.

.TP
\fB \-v \fR
Prints the scripts version number and exits.


.SH CONFIGURATION

The script has to know which version of database is beeing used by digikam. 
The script needs this information to find the correct sqlite binary to 
start queries to the database.
.sp
You have to configure the script by setting the path to the sqlite binary that
is used by the script to query the digikam database digikam.db. Since older
digikam version use sqlite in version 2, but later digikam 0.80 versions
needs sqlite version 3 you have to take care to install the correct version of
sqlite for the installed digikam version and to set the path to the correct
sqlite executable in the scripts head:
.sp
Choose

$SQLITE="/usr/bin/sqlite3"; 

for digikam version 0.8x and 0.9x and 

$SQLITE="/usr/bin/sqlite";  

for digikam version 0.7x.

.SH EXAMPLE

A call to digitaglinktree is shown below:

digiTagLinktree -r /home/user/photos -l /home/user/photos/tags \
            -d /home/user/photos/digikam.db

In this example digikams photo root denoted by -r is /home/user/photos where all of the photos 
can be found that are managed by digikam. The option -l /home/user/photos/tags
tells the script that all the subdirectories and symbolic links will be placed in 
the directory /home/user/photos/tags. Because the link directory is 
below digikams root directory in this example, you will see a new album in digikam
after running the script that contains the exported tag structure with all the photos inside. 
Since only links are used here this tag structure does hardly need any additional space on your
harddisk. 

.SH AUTHORS
.B digitaglinktree
was written by Rainer Krienke <krienke at uni-koblenz.de>