digitaglinktree(1)						Linux User's Manual						digitaglinktree(1)

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 pho-
       tos 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  con-
       tains  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  ar-
       chive 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 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  ar-
	      chive. 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 direc-
	      tory. 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 beeing 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 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	-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.

	-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 -r /home/user/photos -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.

AUTHORS

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

								   16 Aug 2006							digitaglinktree(1)