1digitaglinktree(1)            Linux User's Manual           digitaglinktree(1)
2
3
4

NAME

6       digitaglinktree  -  Export  tag  structure  of photos in digikam to the
7       filesystem.
8

SYNOPSIS

10       digitaglinktree
11
12       -l taglinkdir | -A archivedir
13
14       -d database
15
16       [-r rootdir]
17
18       [-H|-f|-a|-v|-C]
19
20

DESCRIPTION

22       digitaglinktree will create a linktree for  all  photos  in  a  digikam
23       database that have tags set on them. Tags (like eg. "family", "events",
24       ...)  are used in digikam to create virtual folders  containing  images
25       that all have one or more tags assigned.  Please note: Photos that have
26       no tags at all assigned are silently ignored by this script.  The  pro‐
27       gram  will  not  modify  or  even touch your original photos managed by
28       digikam.
29
30
31       The script can be used in two ways: If you call  it  using  Option   -l
32       taglinkdir   the  script  will  create  the  user  specified  directory
33       taglinkdir and inside this directory it will create sub directories for
34       digikam  tags   set  on the photos. Inside these subdirectories it will
35       finally  place symbolic or hard links  (see -H) to  photos  having  the
36       tags  in question.  As a result you will see the tags of your photos as
37       folders and in these folders you will find links to your original  pho‐
38       tos.
39
40
41       In  this  way  you can access the collection of all images that share a
42       certain tag by changing directory to the folder with the tags name cre‐
43       ated  by this script.  This allows you e.g. to run JAlbum a photo album
44       software that needs to find the pictures to be put into a web album  in
45       the  filesystem  because  JAlbum cannot access digikams virtual folders
46       directly.
47
48
49       The second way of calling this script is the so called archive-mode  by
50       setting option  -A archiveDir.
51
52       Archive  mode  is  thought for people who want to archive tagged photos
53       independently of digikams root  directories  and  the  photos  therein.
54       This  way  you can put your photos and their tag structure in eg. a tar
55       archive and send it  to a friend, who can look at the photos via  their
56       tag  structure.  In this mode the script creates the directory given as
57       parameter to -A and in this  directory  two  more  subdirectories.  One
58       named  Photos  and  a second named Tags.  The Photos directory contains
59       hard links to your original photos, and the Tags directory  contains  a
60       subdirectory  for each Tag used by any of your photos. Inside this sub‐
61       directory there are links (either symbolic or hard links) to the  files
62       in  the  Photos directory. This way the archive  directory needs nearly
63       no additional space on your harddisk  and  you  have  an  archive  that
64       allows you or a friend to easily look at the photos tag structure.
65
66       Another  benefit  from  using  this  script  is that you have kind of a
67       backup of your tag settings for all of your photos. The backup is  sim‐
68       ply  the  directory  structure  containing links to the original images
69       that wear the tags.  This could become important if for whatever reason
70       the digikam.db file gets corrupted or even lost.
71
72

COMMAND-LINE OPTIONS

74        -l taglinkdir
75              Parameter   taglinkdir  denotes  a  directory  in  which the tag
76              structure of all your photos stored in rootdir will be  exported
77              to  by creating subdirectories for each tag and placing symbolic
78              links in these subdirectories that point to the  original  photo
79              wearing  the  tags.  If  calling  the  script  with  option   -l
80              taglinkDir you also have to  specify options -r  rootdir as well
81              as -d database.
82
83
84        -A archivedirectory
85              archivedirectory  denotes a directory into which the script will
86              export the photos  and their tag structure. -A has  to  be  used
87              together  with  option   -r   rootdir if using digikam version <
88              0.10, as well as -d database else  the  script  will  terminate.
89              Inside  the  archive   directory the script will create a Photos
90              and a Tags directory. It will put  hard  links  in  the   Photos
91              directory   that  point  to  your original photos. By using hard
92              links you are independent   of  changes  in  your  digikam  root
93              directory  but on the other hand you are limited to one filesys‐
94              tem.  So the directory given by -r  rootdir  and  the  directory
95              specified for -A archivedir have to be  one the same filesystem.
96              If using digikam in version >= 0.10 you cannot specify -r  root‐
97              dir  .  Instead  the  root  paths  of  all albums are taken from
98              digikams database directly. However still the requirement holds,
99              that  archivedir  has  to be on the same filesystem like all the
100              root directories containing photos you defined in  digikam.   If
101              one  of  digikams root directories is on another filesystem this
102              one will not be processed, since hardlinking the  photos  inside
103              the Photos directory would not work in this case!  The Tags sub‐
104              directory will contain links to the files in the  Photos  direc‐
105              tory. This way you have one archive directory that is completely
106              self contained. You can tar it, send it to a friend or  just put
107              it somewhere for archivel or backup purposes. Usually only those
108              photos will be archived that have a digikam tag set on them.  By
109              using  option -C however you can perform a complete archive. See
110              -C for more infos.
111
112
113        -d database
114              database is the complete path including the filename to digikams
115              photo  database  which  usually  can  be  found in digikams root
116              directory. The files name  is usually digikam.db .
117
118
119        -r rootdir
120              rootdir denotes the digikam base directory containing  all  your
121              photos if you are using digikam in a version before 0.10. If you
122              are using digikam 0.10 or newer you must not use this option. If
123              you  do it anyway you will see a hint that the option given will
124              be ignored because digikams version 0.10 database  contains  the
125              root directories of all albums defined in digikam.
126
127
128        -C    When  the  script is called with option -A archivedir only those
129              photos will be archived (by placing links) in the Photos  subdi‐
130              rectory of archivedir that have at least one digikam tag set. By
131              setting option -C all photos will be  archived to  archivedir no
132              matter  if  they  have a tag set or not. Note: This only changes
133              the contents of the Photos  subdirectory not of the Tags  subdi‐
134              rectory in the archivedir directory.
135
136
137        -a    By default the script will try to create relative symbolic links
138              from the directory  taglinkdir  set by option -l  to  the  photo
139              files  under  rootdir given by option -r. Using this option will
140              result in  absolute symbolic links  beeing  created  instead  of
141              relative ones.
142
143
144        -H    By default the script will create soft (symbolic) links from the
145              Tag-Tree to the photos. By setting option -H the script will use
146              hard links instead. Please note that hard links can only be cre‐
147              ated inside one filesystem. So your photos and the Tag tree have
148              to  be  one  the  same filesystem. If not you will see a warning
149              about this problem and the script will not run.
150
151
152        -f    In digikam photos can have hierachical tags (tags that have sub‐
153              tags).  In  this  case  digitaglinktree  would  by default add a
154              directory for the tag and a subdirectory for each of the subtags
155              of  this tag. By setting  -f  a subtag is treated like a regular
156              tag just as its parent tag so digitaglinktree  will  create  all
157              subdirectories  for  tags and subtags at the same level indepen‐
158              dent of the tag - subtag hierarchy.
159
160
161        -Y    Create year directory under each tag directory. Year information
162              is taken from "Date taken" in database.
163
164
165        -i tag1,..,tagn
166              tag1,..,tagn  Include  only  images  with  tags in the list. Use
167              comma as tag separator. Default is "none". Use "all" to  include
168              all tags at once if you really want this. Better try a list with
169              only some tags first to see how long it takes to complete.
170
171
172        -e tag1,..,tagn
173              tag1,..,tagn Exclude images with tags in the list. Use comma  as
174              tag separator. Default is "none".
175
176
177        -M level_number
178              level_number specify the number of directory level. -M specifies
179              that instead of following normal tag  hierarchy,  it  creates  a
180              hierarchy  combining different tags together and not only within
181              one tag hierarchy  (for  example  combining  Places  and  People
182              tags).   You have to add tags to be included by using the option
183              -i (see above).  Depending on the level given and the number  of
184              tags  you  have  included  and  how many photos you manage using
185              digikam, this option may take  a  considerable  amount  of  time
186              (possibly more than one  hour) to complete!  level_number of "5"
187              seems to be the maximum reasonable level to start with  in  this
188              mode.  Options -A -C -a -H -f not tested with this option!
189
190
191        -V    Verbose mode.
192
193
194        -v    Prints the scripts version number and exits.
195
196
197

CONFIGURATION

199       By  default  this  script  will run with all photo databases created by
200       digikam version 0.10 as well as older version like 0.9 and 0.8. If  you
201       still  have digikam version 0.7 then you have to reconfigure the script
202       itself.
203
204       You have to reconfigure the script by setting the path  to  the  sqlite
205       binary  that  is  used  by  the  script  to  query the digikam database
206       digikam.db. Since very old digikam version use sqlite in version 2, but
207       later  digikam  versions need sqlite version 3 you have to take care to
208       install the correct version of sqlite for the installed digikam version
209       and  to  set  the  path to the correct sqlite executable in the scripts
210       head:
211
212       Choose
213
214       $SQLITE="/usr/bin/sqlite3";
215
216       for digikam version 0.8x and 0.9x and 0.10x
217
218       $SQLITE="/usr/bin/sqlite";
219
220       for digikam version 0.7x.
221
222

EXAMPLE

224       A call to digitaglinktree is shown below:
225
226       digiTagLinktree  -l /home/user/tags
227                   -d /home/user/photos/digikam.db
228
229       In this example we assume that you are running digikam version 0.10  or
230       higher  so  that  no  option -r was used to specify the photo root dir.
231       Instead this information will automatically be  fetched  from  digikams
232       database.
233
234       In  case you want to run the script on a digikam database that was cre‐
235       ated by digikam version 0.9 or earlier you have to use  -r  to  specify
236       the  root  directory where you keep all your photos that are managed by
237       digikam:
238
239       digiTagLinktree -l /home/user/tags
240                   -d /home/user/photos/digikam.db
241
242       In this example digikams photo root denoted by -r is /home/user/photos.
243
244       Option -l /home/user/tags tells the script that all the  subdirectories
245       and symbolic links will be placed in the directory /home/user/tags. The
246       folder was chosen so that the  tags-directory  is  not  under  digikams
247       photo  root.  You may put the tags folder inside digikams photoroot but
248       this is not the preferred method.  Because the link directory  contains
249       only  links this tag structure does hardly need any additional space on
250       your harddisk.
251
252       digiTagLinktree -r /home/user/photos  -l  /home/user/tags            -d
253       /home/user/photos/digikam.db
254                   -i People,Place
255                   -M 2
256                   -Y
257
258       In  this  example  if  you  have  an  image  with  the  tags People/me,
259       Place/home from 1970 it will create the following  directory  (link  to
260       the image under _all directory)
261
262       /home/user/tags/Date/1970/_all/
263
264       /home/user/tags/Date/1970/People/me/_all/
265
266       /home/user/tags/Date/1970/People/me/Place/home/_all/
267
268       /home/user/tags/Date/1970/Place/home/_all/
269
270       /home/user/tags/Date/1970/Place/home/People/me/_all/
271
272       same starting with /Place ...  same starting with /People ...
273
274

AUTHORS

276       digitaglinktree   was  written  by  Rainer  Krienke  <krienke  at  uni-
277       koblenz.de>
278
279
280
281                                 16 Aug 2006                digitaglinktree(1)
Impressum