Provided by: digikam_8.5.0-1ubuntu2_amd64 
NAME
digitaglinktree - Export tag structure of photos in digikam to the filesystem.
SYNOPSIS
digitaglinktree
-l taglinkdir | -A archivedir
-d database
[-r rootdir]
[-H|-f|-a|-v|-C]
DESCRIPTION
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 taglinkdir the script
will create the user specified directory taglinkdir 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
archiveDir.
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.
COMMAND-LINE OPTIONS
-l taglinkdir
Parameter taglinkdir 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 taglinkDir you also
have to specify options -r rootdir as well as -d database.
-A archivedirectory
archivedirectory denotes a directory into which the script will export the photos
and their tag structure. -A has to be used together with option -r rootdir if
using digikam version < 0.10, as well as -d database 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 rootdir and the directory specified for -A archivedir
have to be one the same filesystem. If using digikam in version >= 0.10 you cannot
specify -r rootdir . Instead the root paths of all albums are taken from digikams
database directly. However still the requirement holds, that archivedir has to be
on the same filesystem like all the root directories containing photos you defined
in digikam. If one of digikams root directories is on another filesystem this one
will not be processed, since hardlinking the photos inside the Photos directory
would not work in this case! 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
archival 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.
-d database
database 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 .
-r rootdir
rootdir denotes the digikam base directory containing all your photos if you are
using digikam in a version before 0.10. If you are using digikam 0.10 or newer you
must not use this option. If you do it anyway you will see a hint that the option
given will be ignored because digikams version 0.10 database contains the root
directories of all albums defined in digikam.
-C When the script is called with option -A archivedir only those photos will be
archived (by placing links) in the Photos subdirectory of archivedir that have at
least one digikam tag set. By setting option -C all photos will be archived to
archivedir 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 archivedir
directory.
-a By default the script will try to create relative symbolic links from the directory
taglinkdir set by option -l to the photo files under rootdir given by option -r.
Using this option will result in absolute symbolic links being created instead of
relative ones.
-H 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.
-f In digikam photos can have hierarchical 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 -f 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.
-Y Create year directory under each tag directory. Year information is taken from
"Date taken" in database.
-i tag1,..,tagn
tag1,..,tagn Include only images with tags in the list. Use comma as tag separator.
Default is "none". Use "all" to include all tags at once if you really want this.
Better try a list with only some tags first to see how long it takes to complete.
-e tag1,..,tagn
tag1,..,tagn Exclude images with tags in the list. Use comma as tag separator.
Default is "none".
-M level_number
level_number specify the number of directory level. -M specifies that instead of
following normal tag hierarchy, it creates a hierarchy combining different tags
together and not only within one tag hierarchy (for example combining Places and
People tags). You have to add tags to be included by using the option -i (see
above). Depending on the level given and the number of tags you have included and
how many photos you manage using digikam, this option may take a considerable
amount of time (possibly more than one hour) to complete! level_number of "5"
seems to be the maximum reasonable level to start with in this mode. Options -A -C
-a -H -f not tested with this option!
-V Verbose mode.
-v Prints the scripts version number and exits.
CONFIGURATION
By default this script will run with all photo databases created by digikam version 0.10
as well as older version like 0.9 and 0.8. If you still have digikam version 0.7 then you
have to reconfigure the script itself.
You have to reconfigure the script by setting the path to the sqlite binary that is used
by the script to query the digikam database digikam.db. Since very old digikam version use
sqlite in version 2, but later digikam versions need 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:
Choose
$SQLITE="/usr/bin/sqlite3";
for digikam version 0.8x and 0.9x and 0.10x
$SQLITE="/usr/bin/sqlite";
for digikam version 0.7x.
EXAMPLE
A call to digitaglinktree is shown below:
digiTagLinktree -l /home/user/tags
-d /home/user/photos/digikam.db
In this example we assume that you are running digikam version 0.10 or higher so that no
option -r was used to specify the photo root dir. Instead this information will
automatically be fetched from digikams database.
In case you want to run the script on a digikam database that was created by digikam
version 0.9 or earlier you have to use -r to specify the root directory where you keep all
your photos that are managed by digikam:
digiTagLinktree -l /home/user/tags
-d /home/user/photos/digikam.db
In this example digikams photo root denoted by -r is /home/user/photos.
Option -l /home/user/tags tells the script that all the subdirectories and symbolic links
will be placed in the directory /home/user/tags. The folder was chosen so that the tags-
directory is not under digikams photo root. You may put the tags folder inside digikams
photoroot but this is not the preferred method. Because the link directory contains only
links this tag structure does hardly need any additional space on your harddisk.
digiTagLinktree -r /home/user/photos -l /home/user/tags -d
/home/user/photos/digikam.db
-i People,Place
-M 2
-Y
In this example if you have an image with the tags People/me, Place/home from 1970 it will
create the following directory (link to the image under _all directory)
/home/user/tags/Date/1970/_all/
/home/user/tags/Date/1970/People/me/_all/
/home/user/tags/Date/1970/People/me/Place/home/_all/
/home/user/tags/Date/1970/Place/home/_all/
/home/user/tags/Date/1970/Place/home/People/me/_all/
same starting with /Place ... same starting with /People ...
AUTHORS
digitaglinktree was written by Rainer Krienke <krienke at uni-koblenz.de>
16 Aug 2006 digitaglinktree(1)