design.txt

picty Design Document

Image Photo database, indexing and filtering schema
===================================================

An Image is a structure describing an image identified by filename & mtime,
with optional attributes including photo metadata, thumb and full size
images (with size info) and image type information (color depth, native
format).

The ImageCollection is a sorted list of Images, where the sort order is
determined by the tuple (mtime,filename). Images are initially constructed from
walking a selection of directories

An Index (or View) is a sorted and/or filtered subset of the collection. The Index is a list with items that
are tuples of the  form (IndexVariable, Image) where the IndexVariable can be
mtime, filename, or any metadata. Indexes are used for the display of data in sorted order

GUI and Processing Elements
===========================

ImageBrowser: A thumbnail view of the image collection (sorted and/or
filtered). Images can be viewed in the internal view, loaded into external
programs, cut/copied/dragged into other programs (e.g. nautilus),
selected/deselected for batch operations.

ImageViewer: A viewer and simple editor for single images.

The Worker Backend is responsible for loading the image collection in a background thread.
* Initially the Worker will walk the directory tree and find images
* Found images are stored persistently (and loaded before future directory walks)
* On new sessions, the store is loaded then checked against the filesystem tree for changes
* The worker verifies up to date thumbnails exist and create new ones as necessary
* The Woker then enters a monitoring phase:
    * listens for requests to load thumbnail images for display
    * listens for changes to the file system for adds, deletes or changes to images,
        and updates the main store and any indexes for those changes.
    * receives indexing and filter requests. An indexing request will force a full
        metadata load, metadata should be stored persistently for quick retrieval.

The ImageLoader loads fullsize images and associated metadata for the
ImageViewer. Operation is similar to the operation of the ImageThumbnailer.

Note that thumbs, metadata and fullsize image data are associated with Image
items rather than the ImageViewer or ImageBrowser separating data from the interface.

Backend Processing Logic
===========================

The collection and indexes are manipulated on a single background thread.

Notes:
1. tasks are listed in order of priority
2. all tasks should be interruptable by a higher priority task (i.e. check
periodically for a kill state) but continue after the higher priority
task completes. A task should also be cancellable (e.g. to reset the thumb
cache request)
3. tasks that change the Collection or Index should use a lock during the change
4. ui threads that access the Collection or Index in a way that depends on it not
changing should also use the lock

Pseudo code for the collection managing worker thread:

load imagestore ## may need to put this in the loop if it isn't fast enough
start image monitor
set walk dir task to on
set up inotify monitor for the image folder and all subfolders
while true:
    if no pending tasks wait

    ## Highest priority tasks
    task == quit:
        return
    task == image request:
        load image
        notify requestor
        continue
    task == on screen thumb request:
        continue
    task == build index:
        load metadata if needed
        add image to Index
        if done:
            notify requestor
        continue
    ## Lower priority tasks
    task == verify images:
        remove deleted or changed images from the ImageCollection
    task == walk directory:
        add new images
        get mtime, filename, filesize
        load metadata
        if entire directory walked:
            set monitor state
    task == monitor request to add, remove or update images:
        add or remove images from ImageCollection and Index
    ## Lowest priority task
    task == thumbnailing tasks:
        continue
save imagestore


The view also uses a background thread for loading the full image and sizing it
for the screen. (This is implemented in the ImageLoader class)

While not kill request:
    Wait for request
    on request:
        Load full size image (if not already present)
        Size image to requested size and zoom
        Notify viewer

A refined version

While not kill request:
    Wait for request
    on request quick view:
        Load draft version full size image (if draft or fullsize already present)
        Size image to requested size
    on request zoom view:
        Load full size version of image (if fullsize does not already exist)
        Size image to requested size

Photo metadata
==============

The program uses the exiv2 lib to access image metadata, which includes EXIF, IPTC and XMP
metadata standard. exiv2 provides read/write access for many types of images, but not all.

In principle the picty can provide read and write access to all metadata. However, only a
subset of the metadata is interesting from a collection management standpoint: metadata that
describe the images, place them in time (or location) or core photo.

Attributes Kept in Memory for Sort/Filter:

Date Information:
* Date Taken: "Iptc.Application2.DateCreated", "Iptc.Application2.TimeCreated", "Exif.Photo.DateTimeOriginal"
Descriptive Attributes:
* Title:"Xmp.dc.title"
* Description:"Xmp.dc.description","Iptc.Application2.Caption","Exif.Image.ImageDescription"
* Tags/Keywords:"Xmp.dc.subject","Iptc.Application2.Keywords","Exif.Photo.UserComment"
* Artist:"Iptc.Application2.Byline","Exif.Image.Artist"
* Copyright":"Iptc.Application2.Copyright","Exif.Image.Copyright"
* Rating":"Xmp.xmp.Rating"
* Album:"Xmp.xmp.Label"
Photo Attributes:
* Make:"Exif.Image.Make"
* Model:"Exif.Image.Model"
* Orientation:"Exif.Image.Orientation
* Exposure Time:"Exif.Photo.ExposureTime
* FNumber:"Exif.Photo.FNumber
* ExposureProgram:"Exif.Photo.ExposureProgram
* ExposureBiasValue:"Exif.Photo.ExposureBiasValue
* MeteringMode:"Exif.Photo.MeteringMode
* Flash:"Exif.Photo.Flash
* FocalLength:"Exif.Photo.FocalLength
* SensingMethod:"Exif.Photo.SensingMethod
* ExposureMode:"Exif.Photo.ExposureMode
* WhiteBalance:"Exif.Photo.WhiteBalance
* DigitalZoomRatio:"Exif.Photo.DigitalZoomRatio
* SceneCaptureType:"Exif.Photo.SceneCaptureType
* GainControl:"Exif.Photo.GainControl
* Contrast:Exif.Photo.Contrast
* Saturation:"Exif.Photo.Saturation
* Sharpness:Exif.Photo.Sharpness
* SubjectDistanceRange:Exif.Photo.SubjectDistanceRange
Digital Signature Info (NB: Phraymd does not touch these)
* Software:Exif.Image.Software
* IPTCNAA:Exif.Image.IPTCNAA
* ImageUniqueID:Exif.Photo.ImageUniqueID
* Processing Software:Exif.Image.ProcessingSoftware


Non metadata attributes
=======================

(only filename, mtime kept at this point)

Other useful attributes of images that are properties of the files themselves include:

filename
mtime (last modified time)
height
width
size
format (mimetype)

Thumbnailing
============

The free desktop standard thumbnailing standard recommends keeping thumbnails in ~/.thumbnails:

Using the gnome ui lib on the gnome desktop handles creation and loading from failed,
normal and large thumbnail caches in the following directory structure

+.thumbnails/
    +fail/
      +gnome-thumbnail-factory/
        +failimage1.png
        +failimage2.png
        ...
    +normal/
        +normalimage1.png
        +normalimage2.png
        ...
    +large/
        +largeimage1.png
        +largeimage2.png
        ...

The gnome ui lib handles a few details:

    * Image filenames are actually md5 hashes of the full path to the fullsize image
    (e.g. 'path/to/my/pic.jpg' becomes ''2b83b60c41deed5ed96f2c45cbbcfa32.png')

    * The thumbnail is stored in PNG format with the mtime of the original image set as the Exif Data in the png image

    * A thumbnail is valid if the exif date field matches the mtime of the image

    * Failed images are stored as size zero pngs with the exif date field set appropriately

This is fine for small, single user collections (or even small multi-user
collections). For large collections look-up may be slower on a flat directory
structure (this may be filesystem dependant). For multi-user collections it
would be preferrable to store thumbnails in a common area and allow concurrent access.

Approach 1:

+collection-dir/
  +.thumbnails/
    +fail/
    +normal/
      +img1.jpg
      +img2.jpg
  +img1.jpg
  +img2.jpg
  +subdir/
    +.thumbnails/
      +fail/
      +normal/
        +img1.jpg
        +img2.jpg
    +img3.jpg
    +img4.jpg

drawback --> adds a lot cruft to the image folder


Approach 2:

+collection-dir/
  +.thumbnails/
    +fail/
    +normal/
      +img1.jpg
      +img2.jpg
      +img3.jpg
      +img4.jpg
  +img1.jpg
  +img2.jpg
  +subdir
    +img3.jpg
    +img4.jpg

drawback --> too many image files in one dir?
(tweak on this would be allow .thumbnails to be put anywhere on the shared space)

Collections
===========

No reason not to store more than one collection files. Allow the user to switch
between them at run time. Presumably the user could run multiple instances
of picty with a different collection open in each one.

To support offline collections, need to add an "offline" attribute to the collection object. The offline
attribute gets set if the image folder is missing.

Collection config:
* use thumbnail cache or pull from images
* thumbnail cache location (location of thumbnails)

When the collection is offline:
* cannot open it if the thumbs are not stored on the local system
* should not attempt to scan, verify or update the collection
* do not start an image monitor
* can allow metadata editing
* cannot support the save action and other actions that depend on the physical availability of the file

If the collection is reconnected at runtime:
* force scan, verify, update, thumbnailing
* start directory monitor

Switching collections:
    Stop the monitor
    Save the collection
    Empty the collection of images
    Open the new collection file
    ...