xenial (1) digitaglinktree.1.gz

Provided by: digikam_4.12.0-0ubuntu7_amd64 bug

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 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.

        -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 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.

        -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)