----------------------------------------------------
PicBackFlick -- my fav Flickr back up utility so far
----------------------------------------------------


Features

    - fetch recently changed (or all) images
    - saves original size and, optionally, scaled images provided by Flickr
    - collects additional data about each photo (location, comments, tags, etc)
    - locally web browsable content store
    - suitable for running via cron long term to keep collection current
    - support for video
    - Galleriffic based photo browser w/slide show features
    - can also be used to collect other Flickr users content


Quick Start Guide:

    1- You'll need the Python Flickr API (previously known as "Beej's Python Flickr API")
       If you have a recent Debian / Ubuntu setup you should be able to install it via--
         sudo apt-get install python-flickrapi
       Otherwise, see the installation instructions at http://stuvel.eu/flickrapi

    2- You need your own Flickr API key and secret, this only takes a moment from:
         http://www.flickr.com/services/api/keys/apply/
        
    3- Set up your config file. picbackflick.py will create an example for you:

         bash$  ./picbackflick.py -d 3

         ~/.picbackflick.conf doesn't exist, a new one has been created for you which you must now edit

    4- Do the trick. This will grab any photos updated in the last 3 days. 

         bash$  ./picbackflick.py -d 3
       
       The first time you run the application it will walk you through an authorisation step
       which is described here: http://stuvel.eu/media/flickrapi-docs/documentation/#authentication

    5- Admire your efforts.

         bash$ cp -r gallerific photos.html ~/flickr_backups
         bash$ firefox ~/flickr_backups/photos.html

       You should see a thumbnail for each photo along with some other info.
       See the 'Photo Browsing' section below for more.

       Your photos can be found in ~/flickr_backups/img/ organised by date of upload.
       
    Run the script with -h to see more options. Run the script with no options and it will
    look for any new photos which have been added since the last time.


Copying:

    PicBackFlick uses the MIT/X license.


Configuration

     ~/.picbackflick.conf is the default application (INI formatted) config file.
     
     PicBackFlick will create one if it doesn't already exist but you will need to edit it
     in order to do anything useful.
     
     Settings:
     
       api_key
       api_secret
         You'll need to place your Flickr API key and secret there before you can download photos.
         Go to http://www.flickr.com/services/api/keys/apply/ and fill in the form to get yours.

      flickr_username
        Set this to the username which appears in your Flickr photo page URL. This is used to
        compose links to your photo pages
        
      photos_path = ~/flickr_backups
        This is where all your photos and related data will be stored.     


What Gets Fetched?

    On startup, PicBackFlick looks for ~/flickr_backups/last_updated to see how for back in time to 
    look for new or updated photos. On completion, this file is updated. If the file doesn't exist
    it collects all your photos.
    
    If the --days-ago option is given then last_updated is not consulted and any changes in the past
    given days are fetched. Once done, last_updated is set to now.
    
    If an image or video has already been fetched it will not be downloaded again.
    

Image Store

    Images are placed in img/ under the photos_path directory. Under img/ are directories for 
    each month then each image size (o,s,_ for original, small and 500x). Flickr doesn't have a
    size code for the the 500 max dimension size so we use _ . 


    Examples:
     ~/flickr_backups/img/2012-12/s/123456789_s.jpg
     ~/flickr_backups/img/2012-12/_/123456789__.jpg
     ~/flickr_backups/img/2012-12/o/552833895_o.png
     
    See http://www.flickr.com/services/api/misc.urls.html for more about the image sizes 
    available from Flickr
    
    Video files are stored under ~/flickr_backups/video/ per:
        ~/flickr_backups/video/95/552833895.mov

        (TODO confirm that naming for videos, should switch to date scheme.)

    Videos will also have poster images in the img/ directories including an 'original'.

    If you want more image sizes fetched, look for self.options.store_image_sizes and
    valid_sizes in the code. In future, the sizes list will be a configuration option.


Info Store

    TODO: change all this
    TODO: describe new full json file format and location

    NB: it's possible this storage format could change but it seems to be working for now.
    I can imagine some changes could be required to support the tagging and sets features
    but maybe not.

    The detailed data for each photo is stored in an individual json file under 
    ~/flickr_backups/info/ and named per:
        ~/flickr_backups/info/95/552833895_full.js
    
    Each photo also gets an expurgated json file which contains: title, video file extension 
    (if there is one), and the extension of the original photo url (if not jpg). It is named 
    per:
        ~/flickr_backups/info/95/552833895_.js
        
    Each photo record file is not strictly a json file, the photo value is given a variable 
    assignment in an object array called pbf. The key is composed of the photo upload time 
    and the photo ID. This allows the list to be reliably sorted as they appear in your photo 
    stream. Photo IDs are not assigned in a strict time ordered sequence.
    
        pbf['1300347013_5534286708'] = { "id": "5534286708", "t": "Dancing"... }
    
    The expurgated json files are also collected in a single file, ~/flickr_backups/photo_db.js
    As the json files are created they are appended to this file. Updated image data might 
    be repeated but when evaluated the last one is the value used.
    
    You can rebuild photo_db.js by running PicBackFlick with the -w command line option.


Photo Browsing

    You can browse the photos directly by visiting them at:

    ~/flickr_backups/year-month/day/size-code/id_size-code.ext

    The Galleriffic jquery plugin is also available. Copy photos.html and the 
    gallerific directory to ~/flickr_backups then load photo.html in a web browser. 

    At present, this browser doesn't work well with very large photo collections as it 
    loads all thumbnail images in a (mostly hidden) list. My collection of 6000+ sometimes 
    works and sometimes doesn't. 

    With some changes, the Galleriffic interface could be made to perform well with large
    sets.